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Preface 



DECnet-DOS Version 1.1 is the collective product name for the following set of soft- 
ware products: 

• DECnet-DOS Version 1 . 1 which runs on the IBM PC/XT, IBM Personal Computer 
AT, and the IBM PC personal computers. These computers require the IBM DOS 
operating system V2. 10 and/or V3. 10. 

• DECnet-Rainbow Version 1 . 1 which runs on the Rainbow 100 computer systems . 
The Rainbow 100 requires the MS-DOS operating system V2. 1 1. 

DECnet-DOS software, coupled with the appropriate hardware, allows a Rainbow 100 
system to connect to a DECnet network, and to act as a DECnet Phase IV end node. It 
also enables IBM personal computers: PC, PC/XT, and Personal Computer AT to con- 
nect to a DECnet network. 

Manual Objectives 

The DECnet-DOS Programmer's Reference Manual discusses software requirements 
for creating DECnet-DOS applications. It provides detailed information on the use of C 
and MS-DOS system calls supported by DECnet-DOS. It discusses software consider- 
ations when developing DECnet-DOS applications in C or assembly programming lan- 
guages. 

It also assumes that you are familiar with the DECnet and the MS-DOS environments. 
Intended Audience 

This manual is designed for application developers who are responsible for creating 
DECnet-DOS applications. 
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Structure of the Manual 

This manual consists of 6 chapters and 8 appendices. 

• Chapter 1 presents an overview of the DECnet-DOS programming environment. 
It discusses the features of DECnet task-to-task communication. 

• Chapter 2 describes standard MS-DOS function calls used for transparent file 
access. 

• Chapter 3 discusses standard MS-DOS function calls used for transparent task-to- 
task communication. 

• Chapter 4 details the use of C language for nontransparent task-to-task communica- 
tion. The socket interface calls are described in alphabetical order. Each descrip- 
tion includes the call's syntax, argument (s) and associated error/completion status 
codes. 

• Chapter 5 discusses socket interface utilities including those that access network- 
related databases. 

• Chapter 6 discusses the use of assembly language for nontransparent task-to-task 
communication. It details the network process function calls supported by DEC- 
net-DOS. They are described in a manner similar to the calls in Chapter 4. 

This manual also contains 8 appendices: 

• Appendix A lists common definitions for the socket network interface. 

• Appendix B details the format of the data structures used with the socket interface 
and assembly language network process interface calls. 

• Appendix C lists error completion codes for DECnet-DOS task-to-task communica- 
tions and transparent file access operations. 

• Appendix D summarizes the DECnet system error messages. 

• Appendix E lists DAP error messages that provide extended error information to 
transparent file access operations. 

• Appendix F summarizes extended error messages for transparent file access opera- 
tions. 

• Appendix G lists specific socket interface and assembly language network process 
interface calls which cannot be transported to a DECnet-ULTRIX system. 

• Appendix H contains a 'C programming example using socket interface function 
calls. 
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Graphic Conventions Used in This Manual 
Convention Meaning 

bold Words in boldface are considered to be literal and are typed 

exactly as shown. The call name is always shown as literal. 

monospaced Monospaced type indicates examples of system output or user 

"t ype input. System output is in black; user input is in red. 

italics Italics in commands and examples indicate that either the sys- 

tem supplies or you should supply a value. 

(Ctrl/x) Control characters are shown as [ctrl/x ) . where x is an alpha- 

betic character. Press the appropriate key while you hold down 
the fcTRTI key. 

#include <file.h> When #include appears in a SYNTAX section, it indicates an 
include or header file. This type of file contains a collection of 
definitions commonly used throughout a program. You must 
include this file whenever it is required by a specific function 
call. 

Associated Documents 

The following documents are included in the documentation set if you are using a Rain- 
bow computer. 

DECnet-Rainbow Installation Guide 

DECnet-DOS Getting Started 

DECnet-DOS User's Guide 

DECnet-DOS Programmer's Reference Manual 

DECnet-DOS Mini-Reference Guide 

DECnet-Rainbow Release Notes 

You should also have the following manuals available for reference: 

The installation guide and introductory manuals for your computer. 

The following documents are included in the documentation set if you are using an 
IBM personal computer. 

DECnet-DOS Installation Guide 

DECnet-DOS Getting Started 

DECnet-DOS User's Guide 

DECnet-DOS Programmer's Reference Manual 

DECnet-DOS Mini-Reference Guide 

DECnet-DOS Release Notes 
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You should also have the following manuals available for reference: 
The installation guide and introductory manuals for your computer. 
Introduction 

DECnet is the name given to a family of software and hardware communications prod- 
ucts that provide a network interface for Digital operating systems. The relationships 
between the various network components are governed by a set of standards called the 
Digital Network Architecture (DNA). 

DECnet enables multiple computer systems to participate in communications and 
resource sharing within a specific network. The individual computer systems, called 
nodes, are connected by physical communications paths. Tasks that run on different 
nodes and exchange data are connected by logical links. Logical links are temporary 
software information paths established between two communicating tasks in a DECnet 
network. 

DECnet-DOS is a nonrouting implementation of the Phase IV Digital Network Architec- 
ture. The DECnet-DOS software includes the following features: 

• Task-to-task communication between a Rainbow 100 system and/or an IBM per- 
sonal computer: PC, PC/XT or a Personal Computer AT and any Phase III system 
connected to a DECnet router, or any other Phase IV system. 

• Limited network management and maintenance functions . 

• Transport facilities that permit programs to access remote files. 

• Virtual disk and printer, and remote terminal capabilities. 

• Mail utility that lets you send messages and text files to other nodes in the network. 

• Provides file access, for other users in the network, to the files local to your per- 
sonal computer. 
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1 

Introduction to Network Programming 



DECnet-DOS allows Rainbow 100 personal computers, and IBM personal computers: 
PC, PC/XT and Personal Computer AT to participate as end nodes in DECnet computer 
networks. DECnet-DOS nodes can either connect directly to an Ethernet local area net- 
work, or to an adjacent routing node. The DECnet-DOS software product offers the 
following set of functions: 

• Task-to-task communication. Task-to-task communication is a feature common 
to all DECnet implementations. It allows tasks or application programs to commu- 
nicate with each other. Cooperating tasks on different nodes issue DECnet calls 
which enable them to exchange data over a logical link. 

DECnet-DOS allows you to create C and assembly language programs that use non- 
transparent task-to-task communication functions. A set of DECnet utility func- 
tions enable you to access the network node database and manipulate the data. 

DECnet-DOS supports the DECnet-ULTRIX task-to-task network communica- 
tions interface. Any DECnet-DOS C program, using compatible DECnet-ULTRIX 
network interface calls, can be transported to DECnet-ULTRIX systems. (See 
Appendix G for possible exceptions.) 

A simpler programming interface allows DECnet-DOS tasks to exchange data with 
a remote network program. To perform transparent operations, tasks use standard 
MS-DOS I/O system calls. 

• Network Resource Access. DECnet-DOS offers a set of utilities that allow a user 
to access network resources. Using a DECnet-DOS utility, files can be transferred 
between a Rainbow or an IBM PC, PC/XT, and PC AT computers, and another node 
in the network. Transparent file access is also available to a DECnet-DOS task by 
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adding network location information to an MS-DOS path name string. Accessing 
remote DECnet files is accomplished with standard MS-DOS I/O system function 
requests. 

With DECnet-DOS, users can establish a virtual terminal connection to a multi- 
user remote DECnet system. (The remote system must provide similar support.) 
This feature allows for sharing of resources and application development tools of 
larger DECnet systems. 

DECnet-DOS provides the capability to access remote network devices. A utility 
program allows you to share remote printers and disks as if they were directly con- 
nected to your personal computer. 

• Network Management. Limited network management is available with DECnet- 
DOS. This feature serves three primary functions: to configure a DECnet-DOS 
node, display statistical and error information, and test the operation of the net- 
work connection. 

Figure 1-1 shows personal computers running DECnet-DOS in an Ethernet local area 
network. 
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Figure 1 -1 : Personal Computers in an Ethernet LAN 
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1.1 Concepts 



Before you can create a DECnet-DOS application, you need to understand the follow- 
ing programming concepts: 

• Client and server tasks. Client and server tasks communicate through sockets. 
These tasks exchange data over logical links. 

• Sockets. Sockets are the basic building blocks for DECnet-DOS task-to-task com- 
munication. They are created by tasks for sending and receiving data. They contain 
information about the status of the logical link connection. 

1.1.1 Client and Server Tasks 

DECnet-DOS communication requires cooperation between two programs or tasks. 
For the purposes of defining the DECnet-DOS programming interface, a distinction is 
made between the client task which initiates a connect request, and the server task 
which waits for and accepts or rejects the connection. 

A client task is the program which initiates a connect request with another task. A 
server task is the program which waits for and accepts/rejects the pending connect 
request. 

Once a logical link is established, the client and server tasks have a peer-to-peer relation- 
ship. The operations performed on their respective sockets are symmetrical. Either 
task can act as the source or receiving task and can send and receive data, or terminate 
the logical link at any time. 

1.1.2 Sockets 

The basic building block for DECnet-DOS communication is the socket: an addressable 
endpoint of communications within a program or task. A task uses the socket to send 
and receive data to and from a similar socket in another task. Figure 1-2 illustrates the 
use of sockets within DECnet-DOS tasks. 

DECnet-DOS supports stream sockets and sequenced packet sockets. Stream sockets 
cause bytes to accumulate until internal DECnet buffers are full. The receiving task 
does not know how many bytes were sent in each write operation. Sequenced sockets 
cause bytes to be sent immediately. The receiving task receives those bytes in one 
"record". 

A DECnet-DOS program can detect any potential problems by polling the socket's 
status, or by receiving error status in response to network requests. 
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Figure 1 -2: Sockets: Basic Building Blocks for DECnet-DOS Intertask 
Communication 
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1.1.3 Blocking and Nonblocking I/O Operations 

DECnet-DOS allows tasks to send and receive data without waiting for the completion 
of the operation. This mode of operation is called nonblocking I/O. When nonblocking 
is set, socket operations return to the calling program after the operation has been 
started, but not necessarily completed. Some operations must be restarted. On the 
other hand, the default mode for socket operations is blocking I/O. When blocking I/O 
is set, DECnet-DOS does not return control to the calling program until the operation 
has been completed. 

1 . 1 .4 Node Names and Addresses 

Each system in a DECnet network has a unique node name and address. A node name 
can have 1 to 6 alphanumeric characters with at least one alphabetic character. A node 
address is a binary number which consists of an area number and a node number. An 
area consists of a group of interrelated nodes. Multiple areas are typically used only in 
large networks. When initiating a connection with a remote node, you must identify 
that node with a name or address. 

1.1.5 Network Object Numbers and Task Names 

Client tasks can specify the server task that they want to communicate with by using 
network object numbers and task names. Network object numbers range from 1 to 255- 
Numbers 1 to 127 are assigned to generic network servers. Numbers 128 to 255 are 
available for user-written tasks. When a user specifies a task name, the object number 
must be zero. 

The server task must be installed as a network task on the remote node. In the context 
of DECnet-DOS, the server task declares his network object number and task name 
with the bind function call. 

1 .1 .6 Access Control Information 

Access control information contains arguments that define your access rights at the 
remote node. It consists of three character strings: user ID, password and account num- 
ber. Access control verification is performed according to the conventions of the desti- 
nation system. For some systems, the access information is the log-in data used by the 
client program. 

1.1.7 Optional User Data 

DECnet-DOS allows up to 16 bytes of optional user data to be exchanged between 
tasks when connecting to/disconnecting from logical links. 
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1 .2 Forms of Task-to-Task Communication 



DECnet-DOS supports two forms of task-to-task communication: transparent and non- 
transparent. Transparent communication provides a subset of the functions used by a 
program to exchange data with other network programs. Nontransparent communica- 
tion allows you to use the full range of DECnet-DOS task-to-task communication. 

1 .2.1 Transparent Communication 

DECnet-DOS transparent communication provides C and assembly language tasks 
with the basic functions to communicate over the network. These tasks perform stan- 
dard MS-DOS system I/O operations. This form of I/O lets you move data with little 
concern for the underlying DECnet interface. 

The DECnet-DOS transparent functions include the initiation and establishment of a 
logical link, the orderly exchange of messages between both tasks, and the controlled 
termination of the communication process. Chapter 3 discusses the MS-DOS function 
requests that support transparent task-to-task communication. 

Figure 1-3 shows the series of events that occur during transparent task-to-task commu- 
nication. 
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Figure 1 -3: Transparent Task-to-task Communication 
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1 .2.2 Nontransparent Communication 



DECnet-DOS nontransparent communication provides the same functions as DECnet- 
DOS transparent communication plus additional system and I/O functions. For exam- 
ple, you can use network protocol features such as optional user data on connects and 
disconnects, and out-of-band messages. 

DECnet-DOS allows you to create C and assembly language programs that use non- 
transparent communication functions. A C program should use the socket interface 
calls to perform DECnet functions. These calls are detailed in Chapter 4 of this manual. 
A set of DECnet utility functions are also provided with DECnet-DOS. These functions 
are used for accessing the network node database and manipulating the data. The DEC- 
net utility functions are detailed in Chapter 5 of this manual. 

An assembly language program uses the MS-DOS interrupt function request (6EH) to 
request network process access. Information regarding I/O operations is passed with 
this MS-DOS function request. The information is contained in an I/O Control Block 
(IOCB) data structure. Chapter 6 details how to create a DECnet-DOS program using 
the assembly language network process interface calls. This chapter details the set of 
calls used for assembly language programs. 

1 .3 Task-to-task Communication Functions 

This section describes the functions that the client and server tasks request to communi- 
cate with each other. Illustrations that appear in this section use the socket interface 
calls to show task-to-task communication capabilities. 

1 .3.1 Establishing a Logical Link 

The creation of a logical link is a cooperative venture. Two tasks must agree to commu- 
nicate before you can have an established logical link. The process of establishing a logi- 
cal link is detailed in Figure 1-4 . A logical link connection is required before data can be 
exchanged between two tasks. 

To begin the process, the server task creates a socket supported by DECnet. When this 
socket is first created, it has no assigned name or number. An object name or number is 
assigned to the socket. The name or number is required for use in future listening opera- 
tions. The socket declares itself as a server which is available for client connections. 

In turn, the client task must create a socket supported by DECnet. The client task can 
set up access control information and/or optional connect data. (See Sections 1.1.6 and 
1.1.7 for an explanation of each). The system returns an integer value called a socket 
number. Subsequent DECnet-DOS function calls on this socket will reference the asso- 
ciated socket number. At this point, the client task requests a logical link connection to 
another task. Any optional user data and/or access control information is sent along 
with the connection request. 
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The server task can define how it accepts or rejects an incoming connection request. 
There are two options: 

• The server task can immediately accept the connection request. In this case, any 
optional user data and/or optional access control information is not used by the 
task. A logical link has successfully been established between the two tasks. 
Another socket is also created for the server task. Using the new socket, the server 
task can exchange data with the client task. The original socket remains open for 
the server task to listen for other incoming connection requests. 

• For nontransparent communication only, the server task can defer making a deci- 
sion about accepting or rejecting the incoming connection request. When the 
deferred option is set, the server task can examine any optional user data and/or 
optional access control information. It can then send optional user data with an 
acceptance or rejection message to the client task. The client task then retrieves the 
optional user data and/or status message. 

If the connection failed, another attempt can be made at establishing a logical link. 
If the connection was successful, the logical link is established and another socket 
is created for the server task. Using the new socket, the server task can exchange 
data with the client task. The original socket remains open for the server task to lis- 
ten for other incoming connection requests. 
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Figure 1 -4: Establishing a DECnet Logical Link 
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1 .3.2 Sending Normal Data Messages 



Either task can send normal data to its peer. It must specify the socket used for transmit- 
ting the message, the buffer containing the outgoing message, and the buffer size. If the 
socket is set to blocking I/O, and no buffer space is available to hold the outgoing mes- 
sage, the transmission is blocked until resources are freed up. If the socket is set to 
nonblocking I/O, an appropriate error message is returned to the user. 

When the asynchronous form of the SEND call is used, control returns to the calling 
program immediately after the DECnet network process records the request. The net- 
work process may complete the request immediately or wait for a later time. To check 
to see if the data was sent, you can either use a callback routine or poll for status. Sec- 
tion 6.7.15 details the asynchronous form of the SEND call. 

Figure 1-5 shows normal data being sent over a logical link. 



CLIENT TASK 



SERVER TASK 



PROG 3 



PROG 1 




TWO230 



Figure 1 -5: Sending Data Messages over a DECnet Logical Link 
1.3.3 Receiving Normal Data Messages 

Either task can receive normal data from its peer. It must specify the socket used for 
receiving the message, the address of the buffer which will store the incoming message, 
and the buffer size. If the socket is set to blocking I/O, and no messages are received, the 
task waits for a message to arrive. If the socket is set to nonblocking I/O, and no data is 
ready to be received, an appropriate error message is returned to the user. 
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When the asynchronous form of the RCVD call is used, control returns to the calling 
program immediately after the DECnet network process records the request. The net- 
work process may complete the request immediately or wait for a later time. To check 
to see if the data was received, you can either use a callback routine or poll for status. 
Section 6.7. 12 details the asynchronous form of the RCVD call. 

Figure 1-6 shows data being received over a logical link. 

CLIENT TASK SERVER TASK 

PROG 3 PROG 1 



| RECV 




TW0229 

Figure 1 -6: Receiving Data Messages over a DECnet Logical Link 
1 .3.4 Out-of-Band Messages 

Out-of-band messages are unsolicited, high priority messages sent between non- 
transparent communication tasks over a logical link. An out-of-band message usually 
informs the receiving task of an unusual or abnormal event in the sending task. The 
valid range for the message size is 1 to 16 bytes. 

Out-of-band messages are always sent ahead of outstanding normal messages. Unless 
certain error conditions exist, an out-of-band message is always sent even if the socket 
is set to blocking or nonblocking I/O. 
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1 .3.5 Terminating Network Activity and Closing the Logical Link 



The process of terminating network activity can begin with either the client or server 
task. To initiate close down for nontransparent communication, either task can send 
up to 16 bytes of optional disconnect data to another task. The optional disconnect 
data is sent with an abort or disconnect option. 

Figure 1-7 provides an example on how sockets are deactivated, and the logical link 
connection is broken. The close down steps, as depicted in Figure 1-7, include: 

• The server task sets up optional disconnect data. 

• The server task deactivates its socket used for exchanging data. 

• The server task can also deactivate the original socket on which it listened for 
incoming connection requests. 

• The client task retrieves any optional disconnect data. At some point in time, the 
task should also deactivate its original socket. 

• The logical link connection is broken. 

Hence, the sockets are reclaimed as network resources which are made available for 
future assignment to this task or another task. 
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Figure 1 -7: Closing Down the DECnet Logical Link Connection 
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1 .4 Transparent File Access 



Using DECnet, programs in one node can transparently access a file in another node. 
Transparent file access enables user programs to perform standard MS-DOS system I/O 
operations. This form of I/O allows you to move data with little concern for the under- 
lying DECnet interface. 

To perform transparent access operations on remote files, use the MS-DOS function 
requests detailed in Chapter 2. 
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2 

Transparent File Access Operations 



Using DECnet, a program in one node can transparently access a file in another node. 
Transparent file access enables user programs to perform standard MS-DOS system I/O 
operations. This form of I/O allows you to move data with little concern for the under- 
lying DECnet interface. 

Transparent file access functions allow you to open and close a remote file, create or 
delete a remote file, and read from or write records to a remote file, submit a batch job 
and search a directory for a specific file or files. 

2.1 Introduction to Transparent File Access 

In the context of transparent file access, the program that requests remote file access is 
called the client program. At the remote node, the DECnet system program that 
receives the request is called the server program. For DECnet-DOS, the client program 
is a user-written program. The server program is a form of the File Access Listener 
(FAL). FAL receives remote file access requests from the network. FAL completes con- 
nections initiated by remote accessing user programs and translates them into calls to 
the file system at the remote node. FAL then sends or receives the resulting file data 
back to the accessing program. At the client node, special routines reformat the data to 
make it conform to local or remote file structures (depending upon I/O direction). 

Before accessing any remote files, you must install the Transparent File Access utility. 
TFA can be installed at every boot time (See the DECnet-DOS Installation Guide or 
the DECnet-Rainbow Installation Guide for installation details); or installed by typ- 
ing the following start-up command line: 

E>TF A CRED 
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The system responds with one of the following messages: 

DECnet - TFA Version 1.1 installed - 

or 

DECnet - TFA Version 1.1 has already been installed - 

Once the utility is installed, you can request network access by including a subset of 
MS-DOS system calls in your program. (Refer to Table 2-3.) These calls activate Trans- 
parent File Access Routines (TFARs). The TFARs build, send, receive and interpret DEC- 
net file access messages. These messages are defined by the Data Access Protocol 
(DAP). DAP messages control the execution of remote file access, and outline proce- 
dures to accomplish specific file operations . 

A user program does not handle remote file access operations directly. DECnet-DOS 
includes system software that sends and receives DAP messages on behalf of user pro- 
grams. DAP-speaking TFARs at the local node exchange DAP messages with the DAP- 
speaking server FAL at the target node. 

2.2 Initiating Transparent File Access 

Transparent file access operations require an extended handshake sequence being per- 
formed at the beginning of the operation. This extended handshake occurs when the 
user program issues an initial file access call (for example, open, create, delete, submit, 
etc.) to a remote file. The handshake sequence includes the TFARs setting up the logical 
link connection, and exchanging file access messages to initialize the DAP environment 
for pending file operations. 

The initial access to the remote file passes the following information to TFARs in the 
local file system: 

• remote file name string 

• access control information 

2.2.1 Remote File Name 

The file name string specifies the remote node name, and the file on that node to be 
accessed. It includes the device, directory, file name, extension and version number of 
the remote file. Since the remote file system actually carries out the requested file opera- 
tion, you must be familiar with the conventions used for identifying files at the remote 
node. 

2.2.2 Access Control Information 

Access control information provides access rights to the remote system. It consists of a 
user identification name, a password associated with the user identification, and addi- 
tional accounting information required by the remote system. To supply access control 
information, you must follow the syntax detailed in Section 2.7. 1 of this chapter. 
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2.3 File Characteristics 



A file has specific characteristics that determine how the file is transferred between 
local and remote systems. 

The following sections discuss the effects of file characteristics on remote input and 
remote output files. A remote input file is a file located on a remote DECnet host that is 
read by an MS-DOS system. A remote output file is a file located on a remote DECnet 
host that is written to by an MS-DOS system. 

2.3.1 File Attributes 

File attributes for remote input files are determined by the remote file and the remote 
file system. For example, an ASCII file cannot be redefined as an image file. 

File attributes for remote output files are determined by the format of the local file and 
the type of remote file system. 

The set of file attributes are: 

• File Organization. DECnet-DOS only supports sequential files. A sequential file 
has records arranged one after the other. The first record written is the first record 
in the file; and the record written most recently is the last record in the file. 

• Data Type. A remote file can have an ASCII or image data type. Depending on the 
file's record attribute, record format and the remote file system type, DECnet- 
DOS can reformat ASCII data. On the other hand, DECnet-DOS cannot convert 
image data type files. 

• Record Format. This particular file attribute indicates how records are formatted 
within the file. A record can have one of the following formats: 

Undefined records have no declared formats. 

Stream records consist of a continuous series of ASCII characters delimited by car- 
riage return/line feed pairs. 

Fixed length records are identical in size. 

Variable length records can be different lengths, up to a maximum size that you 
specify. The maximum size is fixed at file-creation time and cannot be changed for 
the life of the file. 

Variable-with-fixed length control (VFC) records include a fixed-length control 
field that precedes the variable-length data portion. This format allows you to con- 
struct records with additional data that labels the contents of variable-length por- 
tion of the record. 

• Record Attributes. This characteristic indicates how data is formatted within a 
record. Record attributes (RATs) include implied carriage return/line feed pairs, 
embedded carriage control, FORTRAN carriage control, print file carriage control, 
line sequence ASCII, block, and MACY1 1 . 
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• Fixed Size. If the record format of the remote input file is VFC, this characteristic 
defines the size of each fixed length header. 

• Maximum Record Size. If the record format is fixed, maximum record size (mrs) 
defines the length of each record. For fixed length records, the default size is 128 
bytes. For variable-length records, mrs declares the maximum record size. There is 
no default size. 



2.4 Performing Data Conversions 

To successfully read or write files on other nodes, data must be formatted according to 
the conventions of the respective file system. A system running MS-DOS supports 
stream formatted files. Remote DECnet hosts running heterogeneous operating sys- 
tems can support stream and nonstream file systems: variable-length, fixed-length and 
VFC records. 

The following tables summarize file structure interdependencies when you read or 
write files on remote systems. 

Table 2-1 : Remote Input File Transfers 



File Remote System 

Type Type 

Image Not applicable 

ASCII Stream 

ASCII Nonstream 

ASCII Nonstream 

ASCII Nonstream 



Record Attributes 

Ignored 
Ignored 

Implied CR/LF pair 

FORTRAN, Print or 
LSA carriage control. 

Null, embedded, 
block, MACY 11 



Processing Mode 

No conversion. 

No conversion with embed- 
ded carriage control. 

CR/LF pair appended to 
each record. 

Conversion of carriage con- 
trol done. 

No conversion. 
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Table 2-2: Remote Output File Transfers 



File 
Type 



Remote System 
Type 



Record Attributes 



Processing Mode 



ASCII 



Stream 



None 



No conversion. 

Records determined by LFs. 



ASCII 



Nonstream 



Variable, 
Implied CR/LF 



New line and CR characters 
are dropped. Records deter- 
mined by LFs. 



Image 



Stream 



None 



No conversion. 



Image 



Nonstream 



Fixed: record 
size = 128 bytes. 



No conversion. Last record is 
padded if necessary. 



The following sections detail how the TFARs handle data conversions for remote input 
and output files. 

2.5 Converting Remote Input Files 

During remote file input, a file located on a remote DECnet host is transferred to an 
MS-DOS system. Local handling of the remote file is determined by its attributes and 
the type of remote file system. 

2.5. 1 Binary Image Files 

No record to stream conversion is performed on a binary image file. The file is passed 
to the calling task one record at a time. The size of each record is set by the record attri- 
butes and the maximum record size of the remote input file. If the remote file system 
does not support record attributes (for example, stream), the size is set to 128 bytes. 

The remote file's record format (RFM) and record attributes (RATs) are ignored in this 
type of file transfer. 

2.5.2 ASCII Files 

No data interpretation is performed on an ASCII file coming from a stream file system. 
For ASCII files being copied from a nonstream file system, data handling is determined 
by the remote file system, the remote file's record format and record attributes. 

A nonstream file system can support variable-length, fixed-length, variable with fixed 
carriage control (VFC) record formats and stream record formats. It also supports a 
number of record attributes. The TFARs perform data conversion on ASCII files 
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depending on the record attributes of the remote file. The following section describes 
how TFARs interpret data based on the remote file's record attributes: 

• RAT = Implied LF/CR. No conversion of embedded carriage control characters. A 
CR/LF pair is appended to each record. 

• RAT = FTN, PRN. FORTRAN (FTN) and Print (PRN) carriage control characters 
are converted appropriately to stream file systems. 

• RAT = NULL, Embedded carriage control, Block, MACY1 1 . No data is inserted 
between records. 

2.6 Converting Remote Output Files 

Remote output files are transferred from the local system to a remote DECnet host. By 
default, files are transferred in ASCII mode. The file's record format and record attri- 
butes are determined by the remote file system. A logical record consists of data up to 
and including a CR/LF pair. The TFARs send a file as image if the first logical record is 
not terminated by either a CR/LF or a LF/CR pair. 

2.6.1 ASCII Files 

If the local file is transferred to a remote stream file system, the logical records are 
passed with no data conversion being performed. The file structure defaults are: 

Record Record 
Format Attribute 

Stream NONE 

If the file is copied to a nonstream file system, delimiting CR/LF pairs are dropped from 
the logical records before they are sent. The file structure defaults are: 

Record Record 
Format Attribute 

Variable Implied 
length CR/LF 

2.6.2 Image Files 

If the remote output file is an image file, the records are passed with the following 
default file structure: 

Record Record Maximum Record 

Format Attribute Size (bytes) 

Fixed-length NONE 128 
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Since the default data type for a remote output file is ASCII, the TFARs initially create 
an ASCII file on the remote node. If the first logical record is not terminated by a CR/LF 
or a LF/CR pair, the TFARs will issue a DAP access message complete (purge) message. 
In this case, the TFARs create a new image file on the remote node. This particular file is 
then sent using the data handling defaults for an image file transfer. 

2.7 Using Network File Specifications for Network Access 

MS-DOS system calls requesting network access must pass a specifically formatted net- 
work file specification string. The TFARs intercept these calls, recognize the network 
access request and perform the DAP functions necessary to complete the specified net- 
work operation. 

The network file specification consists of a node specification string, optional access 
control information; and a file name specification string. 

To request network access, use the network file specification string as shown below: 
\\f \node\use r i d\passwo rd\account\\f i I e-spec i f i cat i on 

NOTE 

You must specify either a lowercase f or an uppercase F as part of the 
network task specification string. 

2.7.1 Node Specif ication 

A node specification identifies the remote system where file access operations will take 
place. The node specification string is preceded by two backslashes, the letter f and 
another backslash. The optional access control string follows the node information. 
Each element is separated by a single backslash character. 

If no access control information is supplied, then the default access control informa- 
tion set with NCP is used. If there is no default access information, only the node name 
is used by the TFAR subroutines for processing. 

The node specification string uses one of the following formats: 

1 . To access the remote node with access control information: 
\\f \node\use r i d\password\account\\ 

2. To access the remote node without optional access control data: 
\\f\node\\ 

where: 

node specifies either the name or address of the remote node. A node name 

has a maximum of 6 alphanumeric characters with at least one alpha- 
betic character. A node address is a numeric string including the area 
number in the range of 1 to 63, and the node number in the range of 1 
to 1023. 
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userid 



identifies a user name or log-in ID on the remote system. The user 
name and password set the user's privileges for accessing the remote 
task. A user name has a maximum of 39 alphabetic characters. 



password 



defines a user's password which is associated with user. A user's pass- 
word has a maximum of 39 alphabetic characters. 



account 



identifies a billing account number which is used with the user name 
and password information on some systems. An account number has a 
maximum of 39 characters. If the account information is not required, 
you can omit it from the string. 



2.7.2 File Name Specifications 

The file name specification string identifies the remote file to be accessed. File specifica- 
tion strings cannot contain spaces, semi-colons, left < or right > angle brackets. File 
names must conform to the conventions of the target node. Any unspecified elements 
default to the target system's conventions. Refer to the appropriate programmer's refer- 
ence manual for more details. 

2.8 Passing User Parameters 

Whenever an I/O file operation is invoked, system control is transferred to the TFARs. 
Users pass parameters to and receive results from the TFARs via the MS-DOS function 
requests. The parameters are loaded into or returned to one or more 8086/8088 regis- 
ters. The contents of each register is defined by the specific MS-DOS function call. 

The TFAR subroutines check to see if the proposed I/O operation is a network sup- 
ported call. Network access is signaled by the string \\/\ which begins the network 
file specification string. (See Section 2.7) 

The TFARs parse the network file specification string. If a function call returns a han- 
dle, the TFARs save the handle (and related file specification data) in a database for sub- 
sequent calls requiring network access over the same path. Once the requested DAP 
operation is completed, control is returned to the system and the TFARs. 

2.9 Using the Transparent Network Task Control Utility 

The Transparent Network Task (TNT) Control utility, Version 1 . 1 reports the status of 
the Transparent File Access (TFA) utility as well as the Transparent Task-to-task (TTT) 
utility. It features an on-line help routine which lists supported TNT commands. TNT 
returns DAP messages and other extended error information for assisting in fault isola- 
tion. Using TNT, you can deinstall TFA (and/or TTT) from memory. 

This section deals only with the use of TNT for transparent file access operations. Chap- 
ter 3 discusses TNT and its role in transparent task-to-task communication. 
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2.9.1 Displaying Network Status of the Transparent File Access Utility 

To display the status of TFA, you run TNT. The system responds with a start-up mes- 
sage and one or more network status message(s). 

All errors returned by the Transparent File Access utility are standard MS-DOS error 
messages. However, the Transparent Network Task Control utility provides extended 
error support to transparent file access operations. DAP and other extended error mes- 
sages, returned by this utility, can help you locate problem areas. See Appendices C, E 
and F for a complete list of these error messages. 

NOTE 

When you run TNT, the status of the Transparent Task-to-task utility is 
also reported. 

To invoke TNT, type the following command: 

E> fRETl 

The system responds with a start-up message: 
Transparent Network Task Control VI . 1 

and one or more of the following status message(s): 
DECnet TFA is not installed. 

DECnet TFA has no errors to report. 

DECnet TFA Errors are: 

remote file specification: extended error message 



or 








DECnet 


TTT 


i s not i nsta 1 1 ed . 




DECnet 


TTT 


has no errors to 


report . 


DECnet 


TTT 


Errors are: 




remote 


file 


spec i f i cat i on : 


extended 



where 

extended error message returns an error code from one of the following groups of 
error messages: 

• error codes contained in the external variable errno -Appendix C . 

• DAP error messages (maccode/miccode in octal) - Appendix E. 

• Transparent File Access Routines error messages - Appendix F. 
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2.9.2 On-Line Help 



On-line help provides you with a list of supported TNT commands. To obtain help, 
type: 

E>TNT H EL. P ARED 



The system responds with the following help text: 

Transparent Network Task Control VI . 1 
Transparent Network Task commands are: 

TNT Display status of both TTT and TFA. 

TNT HELP Display this text. 

TNT TTT OFF Remove TTT from memory. 

TNT TFA OFF Remove TFA from memory. 

If you mistype a command, TNT responds with an error message and the list of sup- 
ported TNT commands: 

Transparent Network Task Control VI . 1 
Transparent Network Task command error. 
Transparent Network Task commands are: 



TNT Display status of both TTT and TFA. 

TNT HELP Display this text. 

TNT TTT OFF Remove TTT from memory. 

TNT TFA OFF Remove TFA from memory. 



2.9.3 Deinstalling TFA 

You can remove TFA from memory. Enter the following command line: 

E> r rr <\ f ared 

The system responds with the following text: 

Transparent Network Task Control VI . 1 
The task was removed successfully. 

If TFA could not be removed, one of the following messages is displayed: 
Transparent Network Task Control VI . 1 

TFA cannot be removed because it is not installed or is not installed 
last . 

or if MS-DOS failed on the remove call, 

Transparent Network Task Control VI . 1 
The task could not be removed. 

NOTE 

TFA traps MS-DOS interrupt function call 21H as do other software 
applications. If you want to remove TFA from memory, it must be the 
last task installed which intercepts interrupt 21H. Otherwise, you 
should remove any tasks installed after TFA that also trap 21H, or 
reboot your system to remove TFA. 
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2.10 TFA Programming Considerations 

There are specific MS-DOS function requests that support DECnet-DOS transparent 
file access operations. Table 2-3 provides you with a summary of these calls. When cre- 
ating TFA applications, you should note the following: 

• Some user programs may not accept the TFA network specification string. 

• You should not use unsupported MS-DOS function requests to perform transpar- 
ent file access operations. 

• If you issue a (CTRL/c ) while TFA is active, network operation may be blocked. To 
clear this condition, run the TNT utility. 

2.1 1 MS-DOS Function Requests 

The following table summarizes the MS-DOS function requests used for transparent 
file access operations. Call descriptions appear in Sections 2.11.1 through 2.11.9. 

Table 2-3: MS-DOS Function Requests for Transparent File Access 
Hexadecimal 

Value Function 

3CH Create a file. 

3DH Open a file. 

3EH Close a file handle. 

3FH Read from a file/device 

40H Write to a file/device. 

4 1 H Delete a file from a 

specified directory. 

4BH Load and execute a 

program. 

4EH Find first matching file . 

4FH Find next matching file 



Network Access 

Initiate a logical link request to create a 
remote file. 

Initiate a logical link request to open a remote 
file. 

Close a remote file and terminate a logical link 
connection. 

Read data from a remote file. 
Write data to a remote file. 
Delete a file from a remote directory. 

Submit a remote command file to be exe- 
cuted. 

Search for the first remote file that matches 
the specified file characteristics. 

Find the next file entry that matches the name 
specified on the previous find first call. 
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2.11.1 Close 



NAME 

Close - close a remote file, terminate a logical link connection and deactivate the han- 
dle used for data exchange. 



+ + 

i On 8086/8088 Register Contents 

Entry 

+ + + 

; AH 3 EH 

+ + + 

BX handle for logical link access 
+ + + 



On | 


8086/8088 Register Contents 


Return | 




AX | 


no errors; if carry bit is clear 


I 
j 


error code; if carry bit is set 



Figure 2-1 : Close Function Call 
DESCRIPTION 

The Close function closes the remote file, terminates the logical link connection, and 
deactivates the handle used for data exchange. 

On entry, the BX register contains the 1 6-bit handle value returned by the open or cre- 
ate I/O operation. If the close operation completes successfully, no error is returned in 
the AX register. If an error condition occurs, the appropriate error code is returned in 
the AX register. 

The following error code can occur: 
Hexadecimal 

Value Meaning 

6 An invalid handle value was detected. 

NOTE 

If you issue the Close call with a handle equal to - 1 ; the TFARs will 
interpret the call as a request to abort any active Find Matching File 
operations. 
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2.11.2 Create 
NAME 

Create - initiate a logical link request to create a remote file. 



On 


! 8086/8088 Register Contents 


Entry 


I 


AH 


! 3CH 


DS:DX 


| address of remote file 




| specification string 



On | 


8086/8088 Register Contents 


Return | 




AX | 


handle for logical link access; 


I 


if carry bit is clear 


I 


error code; if carry bit is set 



Figure 2-2: Create Function Call 
DESCRIPTION 

The Create function call enables a source task to initiate a logical link request to create a 
remote file. When the request is made, the file is opened for write operations. On 
entry, DS:DX contains the address of the remote file specification string. Any optional 
access control information is passed as part of the string to the target task. 

On return, the AX register contains an error code or a 1 6-bit handle associated with the 
source task. The returned handle value must be used for subsequent read and write I/O 
operations. 

The TFARs exchange a series of DAP messages with the remote FAL in order to initialize 
the DAP environment and define the requested network access. Each link initialization 
involves an exchange of DAP configuration, attributes and access messages. The config- 
uration messages include information regarding the operating and file systems of the 
source and target systems, and the buffer size. The attributes messages supply informa- 
tion about the file to be accessed. Undefined file attributes are set to default values 
determined by the remote file system. The access message establishes the type of access 
to the remote file. 
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If you are unable to initiate a logical link connection, an error code is returned in the 
AX register. The following set of error codes can occur: 

Hexadecimal 



Value Meaning 

2 The network process may not be loaded. The node name to node 
address mapping is not found in the database file. The target task 
on the outgoing connection is not available. The network is 
unreachable. 

3 The target task was not found. 

4 There are too many active logical link connections. 

5 The remote object rejected the request. 
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2.11.3 Delete 
NAME 

Delete - delete a remote file from a specified directory. 



+ + 

| On | 8086/8088 Register Contents \ 
| Entry | ! 
+ + + 

| AH | 41H j 
+ + + 

| DS:DX | address of network file j 
| | specification string j 
+ + + 



+ + 

| On | 8086/8088 Register Contents | 

| Return j ! 

| AX | error code; if carry bit is set | 
+ + + 



Figure 2-3: Delete Function Call 
DESCRIPTION 

The Delete function call deletes a remote file from a specified directory. 

On entry, DS:DX contains the address of the remote file specification string. Any 
optional access control information is passed as part of the string to the target task. 

If an error condition occurs, the error code is returned in the AX register. The follow- 
ing set of error codes can occur: 

Hexadecimal 

Value Meaning 

2 The network process may not be loaded. The node name to node 

address mapping is not found in the database file. The target task 
on the outgoing connection is not available. The network is not 
reachable. 

5 The remote object rejected the request. 
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2.11.4 Find First Matching File 
NAME 

Find First Matching File - search for the first remote file that matches the specified file 
characteristics. 



+ + 

! On | 8086/8088 Register Contents ! 
I Entry j ! 
+ + + 

I AH | 4EH | 

+ + -- - + 

j DS:DX | pointer to remote directory j 
i | specification string \ 



+ - + 

| On | 8086/8088 Register Contents ! 

| Return | ! 

+ + + 

| AX | error codes; if carry bit is set i 

| current| file name, creation date, ! 
| DMA | file size and creation time; if j 
| data | carry bit is clear j 
| block | j 
+ + + 



Figure 2-4: Find First Matching File Function Call 
DESCRIPTION 

The Find First Matching File function searches for the first file that matches the direc- 
tory specification set by the user. If a directory specification is given without a file spec- 
ification, or includes wildcards; the first matching file is returned. On entry, the DS:DX 
register contains the address of the network file specification string. 

If a file is found that matches the specification string, the carry bit is cleared and the 
information is returned into the current DMA data block as follows: 

• file name bytes 30-42 

• creation time bytes 22-23 

• creation date bytes 24-25 

• file size bytes 26-29 (26-27 low, 28-29 high) 
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The DMA is a portion of memory that is allocated for passing data between processes. 
The user can obtain a pointer to this area by issuing an MS-DOS Get Disk Transfer 
Address function call 2FH. 

If only one matching file is found, the carry bit is not set and an 18 is returned in the AX 
register. If no matching file is found, the carry bit is set, and an error code of 2 is 
returned in the AX register. 

The following set of error codes can occur: 

Hexadecimal 

Value Meaning 

2 The network process may not be loaded. The node name to node 

address mapping is not found in the database file. The target task 
on the outgoing connection is not available. The network is 
unreachable. 

1 8 There are no matching files . 
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2.11.5 Find Next Matching File 
NAME 

Find Next Matching File - find the next file entry that matches the name specified on 
the previous find first call. 



On j 


8086/8088 Register Contents 


Entry | 




+ ■ 




AH | 


4FH 


current | 


must point to a data block 


DMA | 


returned by the previous Find 


address | 


First Matching File function call 



+ + 

| On | 8086/8088 Register Contents | 

| Return j" j 

+ + + 

| AX | error codes; if carry bit is set j 
+ + + 



Figure 2-5: Find Next Matching File Function Call 
DESCRIPTION 

This function call finds the next matching entry in a directory. On entry, the current 
DMA address must point to a data block returned by the previous Find First Matching 
File function call. . 

If a file is found that matches the specification string, the information is returned into 
the current DMA data block as follows: 

• file name bytes 30-42 

• creation time bytes 22-23 

• creation date bytes 24-25 

• file size bytes 26-29 (26-27 low, 28-29 high) 

The DMA is a portion of memory that is allocated for passing data between processes. 
The user can obtain a pointer to this area by issuing an MS-DOS Get Disk Transfer 
Address function call 2FH. 
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When a matching file is found, and it is the last matching file in the directory; an error 
code 18 is returned in the AX register and the carry bit is cleared. Likewise, if no match- 
ing file is found, the carry bit is set and an error code 18 is returned in the AX register. 

The following error code can occur: 
Hexadecimal 

Value Meaning 

1 8 There are no more files . 
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2.11.6 Load and Execute a Program 
NAME 

Load and Execute a Program - submit a remote command file. 

+ + 

| On | 8086/8088 Register Contents I 
I Entry | I 
+ + + 

| AH | 4BH | 

+ + + 

| DS:DX | pointer to remote file | 
| | specification string I 
+ + +■ 



On 


t 8086/8088 Register Contents 


Return 




AX 


error code; if carry bit is set 



Figure 2-6: Load and Execute a Program Function Call 
DESCRIPTION 

This function call allows an existing remote file to be submitted as a batch or command 
file for remote execution. The remote file is not deleted after completion of this call. 
On entry, the DS:DX register contains the address of the network file specification 
string. It specifies the remote file to be loaded and executed in a standard MS-DOS load 
and execute function call, registers ES:BX points to a parameter block defining the com- 
mand file's environment. These registers are ignored for remote command file submis- 
sion. 

If the load and execute is unsuccessful, the carry bit is set and the error reason is 
returned in the AX register. The following error code can occur: 

Hexadecimal 

Value Meaning 

2 The network process may not be loaded. The node name to node 

address mapping is not found in the database file. The target task 
on the outgoing connection is not available. The network is 
unreachable. 
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2.11.7 Open 
NAME 

Open - initiate a logical link request to open a remote file. 



On 

Entry 


I 
I 


8086/8088 Register Contents 


AH 


I 


3DH 


DS:DX 


- + • 

I 

I 


address of remote file 
specification string 


AL 


- + ■ 

I 

- + ■ 


access mode 



+ + 

| On | 8086/8088 Register Contents \ 

j Return | i 

+ + + 

| AX | handle for logical link access; ! 

| | if carry bit is clear | 

I.I I 
| | error code; if carry bit is set | 
+ + + 



Figure 2-7: Open Function Call 
DESCRIPTION 

The Open call enables a task to initiate a logical link request to open a remote file. On 
entry, DS:DX contains the address of the remote file specification string. If you include 
wildcards as part of the specification string, only one file is opened. 

Any optional access control information is passed as part of the string to the target task. 

The access mode is defined in AL and consists of one of the following values: 

• open file for reading 

• 1 open file for writing 

• 2 open file for reading and writing 

If the Open call completes successfully, a 1 6-bit handle is returned in the AX register. 
The handle value must be used for subsequent read and write I/O operations. 
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If an error condition occurs, the carry bit is set and an error code is returned in AX regis- 
ter. 

The following set of error codes can occur: 
Hexadecimal 

Value Meaning 

3 The target task was not found. 

4 There are too many active logical link connections . 

5 Network access was denied. 
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2.11.8 Read 
NAME 

Read - receive data from a remote file. 



+ + 

| On | 8086/8038 Register Contents 1 

i Entry j j 

+ + + 

| AH | 3FH ! 

+ + + 

| DS:DX | address of network message buffer ! 

+ + + 

| CX I size of network message buffer | 

+ + + 

| BX ! handle for logical link access | 
+ + + 



+ + 

| On | 8086/8088 Register Contents | 

| Return j I 

+ + + 

| AX | number of bytes received over the | 

| j logical link; if carry bit is j 

j | clear I 

I I I 
| | error codes; if carry bit is set I 
+ + + 



Figure 2-8: Read Function Call 
DESCRIPTION 

The Read function call allows the target task to read data from a remote file. 

On entry, the BX register contains the 1 6-bit handle value. The CX register contains the 
number of bytes to be received. DS:DX contains the address of the network message 
buffer. 

On return, the AX register contains the number of bytes successfully received by the tar- 
get task. If the carry bit is clear and AX = 0, an end-of-file status is indicated. A single 
read function returns a maximum of one logical record. 

If the buffer is too small for one logical record, no error occurs. The next read con- 
tinues to return bytes until the entire logical record has been read. 

If an error condition occurs, the carry bit is set, and an error code is returned in the AX 
register. 
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The following set of error codes can occur: 
Hexadecimal 

Value Meaning 

5 The logical link was disconnected. 

6 An invalid handle was detected. 
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2.11.9 Write 
NAME 

Write - write data to a remote file. 



On 

Entry 


| 8086/8088 Register Contents 

I 


AH 


- + - - 

| 40H 


DS:DX 


| address of network message buffer 


CX 


| size of network message buffer 


BX 


| handle for logical link access 



+ + 

| On | 8086/8088 Register Contents | 

| Return j | 

+ + + 

| AX | number of bytes sent over the j 

| | logical link; if carry bit is | 

| | clear | 

I ! I 
| | error codes; if carry bit is set | 
+ + + 



Figure 2-9: Write Function Call 
DESCRIPTION 

The Write function call allows the source task to write data to a remote file. 

On entry, the BX register contains the 1 6-bit handle value. The CX register contains the 
number of bytes to be sent. DS:DX contains the address of the network message buffer. 

On return, the AX register contains the number of bytes successfully sent by the source 
task. 

If an error condition occurs, the carry bit is set and an error code is returned in the AX 
register. 
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The following set of error codes can occur: 
Hexadecimal 

Value Meaning 

5 Network access was denied. 

6 An invalid handle was detected. 



2-26 



DECnet-DOS Programmer's Reference Manual 



3 

Transparent Task-to-Task Communication 



DECnet-DOS supports transparent task-to-task communication for high level language 
and assembly language programs. DECnet-DOS supports DOS Version 2.0 XENIX- 
compatible I/O handle calls starting with function request 2FH. Using specific calls, a 
task can perform standard I/O operations, and communicate with another task over the 
network. 

3.1 Transparent Task-to-Task Communication 

Transparent communication provides the basic functions necessary for tasks to com- 
municate over the network. These functions include the initiation, acceptance and 
establishment of a logical link; the orderly exchange of messages between DECnet 
tasks; and the controlled termination of the communication process. 

When accessing the network transparently, you use no DECnet-specific calls to per- 
form these functions. Instead, you use normal I/O statements provided by the applica- 
ble high level language. An assembly language task uses a subset of the MS-DOS func- 
tion requests to perform the same communication activities. 

3.2 Transparent Communication Functions 

This section describes the functions that the client and server tasks use to communicate 
over the network. 
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3.2.1 Initiating a Logical Link Connection 

Transparent communication can only take place after a logical link is established 
between two cooperating tasks. You establish the logical link by issuing a client task 
call that requests a logical link connection. The request is sent to the server task on the 
remote node. 

The interaction that takes place prior to establishing a logical link is termed a 
handshaking sequence. Using transparent task-to-task communication, an MS-DOS 
program can act as either a client or a server. 

3.2.2 Handshaking Sequence for a Client Task 

To initiate the logical link request transparently, a client task performs a file create or 
open operation. This task supplies the following information: 

• The identification of the server node. Every node in the network has a unique 
identifier that distinguishes it from other nodes in the network. Transparent com- 
munication uses a node specification string to indicate the name of the server node. 
(See Section 3.4.1) 

• The identification of the server task. Client tasks specify the server task that they 
want to communicate with by using a network task specification string. This string 
uses network object numbers and task names. Network object numbers range from 
1 to 255. Numbers 1 to 127 are assigned to generic network servers. Numbers 128 
to 255 are available for user- written tasks. 

When a user specifies a task name, the object number is zero. 

High level language client tasks can use standard file opening statements to request a 
logical link connection to the remote task. An assembly language client task uses the 
MS-DOS Create or Open function request to perform the same operation. 

3.2.3 Handshaking Sequence for a Server Task 

A high level language server task performs a file create or open operation to accept the 
logical link connection request. If SYS $ NET is specified as the node name, the task is 
always a server task. An assembly language server task can accept the logical link 
request with either the MS-DOS Create or Open function request. 

3.2.4 Exchanging Data Messages over a Logical Link 

Once the logical link is established, either task can send and receive data messages. A 
coordinated set of write and read operations enable the exchange of data over the logi- 
cal link. For high level language tasks, standard read and write calls are used for data 
exchange. An assembly language task uses the MS-DOS Read and Write function 
requests. The handle returned by the previous Create and Open function requests must 
be specified in all Read 2.\\d"Write function requests. 
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3.2.5 Terminating the Logical Link 

The termination of a logical link signals the end of the communication process between 
two tasks. When network activity is no longer required, either high level language task 
can issue a file closing statement to break the link. Likewise, either assembly language 
task can issue the MS-DOS Close function request to terminate the connection. This 
particular MS-DOS call closes the logical link, and deactivates the original handle used 
for data exchange. 

3.3 Creating a Transparent Communication Task 

Before creating a transparent communication task, you must install the Transparent 
Task-to-Task (TTT) utility. To install this utility, type the following start-up command 
line: 

E> (ret) 

The system responds with either: 
DECnet - TTT Version 1.1 installed 
or 

DECnet - TTT Version 1.1 has already been installed 

Once the utility is installed, a high level language task can invoke standard I/O function 
calls. An assembly language task can use the following MS-DOS function requests. 

Table 3-1 : MS-DOS Function Requests for Transparent Intertask Communication 



Function Network Access 

Create/Open Initiate a logical link request. Accept 

a logical link request. 

Close Terminate a logical link connection. 

Read Receive data over a logical link. 

Write Send data over a logical link. 



Whether you are running a high level or assembly language task, network access 
requires the use of specially formatted task names. These task names are implemented 
as network task specification strings. The strings must be specified with all create and 
open file operation calls. 
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3.4 Network Task Specifications 

The network task specifications consist of a node specification string with optional 
access control information; and a target task specification string. Access control infor- 
mation contains arguments that define your access rights at the remote node. The con- 
trol string contains three fields: user name, password, and account number. Access con- 
trol verification is performed according to the conventions of the remote node. 

The target task can be identified as either a named or numbered object. Named objects 
are user- written tasks which are referenced by a name during a connect request and an 
accept request. The object number for such tasks is 0. Numbered objects are tasks 
which are referenced by a number. The object numbers range from 1 to 255. Numbers 
1 to 127 are reserved for DECnet-specific tasks. Numbers 128 to 255 are available for 
user- written tasks. 

You can access the target task by its object name or number. The network task specifica- 
tion string uses one of the following formats: 

1 . To access the target task by object name with access control information 
\\t\node\user i d\password\account\\ob j ect-name 

2 . To access the target task by object name without access control information 
\\t\node\\ob j ect-name 

3. To access the target task by object number with access control information 
\\t\node\use r\password\account\\#ob j ect -number 

4 . To access the target task by object number without access control information 
\\t\node\\#ob j ect -number 

5 - To establish a server task by object name 

\\t\SYS$NET\\ob j ect-name 
6. To establish a server task by object number 

\\t\SYS$NET\\#object-number 

NOTE 

You must specify either a lowercase t or an uppercase T as part of 
the target task specification string. 

3.4.1 Node Specif ications 

A node specification for a client task names the remote node and supplies optional 
access control data. The node specification string is preceded by two backslashes, the 
letter t and another backslash. The optional access control string follows the node infor- 
mation. Each element is separated by a backslash. 
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The node specification string takes the following format: 
\\t\node\user\password\account\\ 



or 



specifies either the name or address of the remote node. A node name 
has a maximum of 6 alphanumeric characters with at least one alpha- 
betic character. A node address is a numeric string including the area 
number in the range of 1 to 63, and the node number in the range of 1 
to 1023. 

identifies a user name or log-in ID on the remote system. The user 
name and password set the user's privileges for accessing the remote 
task. A user name has a maximum of 39 alphabetic characters. 

defines a user's password which is associated with user. A user's pass- 
word has a maximum of 39 alphabetic characters. 

identifies a billing account number which is used with the user name 
and password information on some systems. An account number has 
a maximum of 39 characters. If the account information is not 
required, you can omit it from the string. 

A node specification string for a server task is always \\t\SYS$NET\\. 

3.4.2 Task Specif ications 

For a client task, the task specification identifies the cooperating task on the remote sys- 
tem. The server task specification identifies the server task. The task can be specified as 
a named or a numbered object. 

The task specification string is expressed in one of the following formats: 
ob j ect-name 
or 

#ob j ect-number 
where: 

object-name specifies the task as a named object. User-written tasks are usually 

addressed as object type plus a name. Digital-specific tasks can be 
addressed by object name. The object name has a maximum of 16 
characters. 

object-number specifies the task as a numbered object. The valid range is 1 to 2 5 5 . 



\\t\node\\ 
where: 
node 

userid 

password 
account 
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3.5 MS-DOS Intercept Routine 



Whenever an I/O file operation call is invoked, system control is transferred to the MS- 
DOS task-to-task intercept routine. Network access is signaled by the string \\A 
which begins the network task specification string. (See Section 3.4 for formats.) The 
MS-DOS intercept routine checks to see if the proposed I/O operation is a network sup- 
ported call. 

The intercept routine parses the network task specification string. It stores away the 
socket numbers for the handles used with the open and create I/O calls. These values 
must be specified with subsequent read, write and close operations. Before one of 
these calls can complete, the intercept routine must verify the current status of the net- 
work handles. 

3.6 Using the Transparent Network Task Control Utility 

The Transparent Network Task (TNT) Control utility, Version 1 . 1 reports the status of 
the Transparent Task-to-Task (TTT) utility as well as the Transparent File Access (TFA) 
utility. It features an on-line help routine which lists supported TNT commands. TNT 
returns extended error information for assisting in fault isolation. Using TNT, you can 
deinstall TTT (and/or TFA) from memory. 

This section deals only with the use of TNT for transparent task-to-task communica- 
tion. Chapter 2 discusses TNT and its role in transparent file access operations. 

3.6.1 Displaying Status of the Transparent Task-to-Task Utility 

To display the status of TTT, you run TNT. The system responds with a start-up mes- 
sage and one or more status message(s). 

All errors returned by the Transparent Task-to-Task utility are standard MS-DOS error 
messages. However, the Transparent Network Task Control utility provides extended 
error support to transparent task-to-task communication. Extended error messages, 
returned by this utility, can help you locate problem areas. 

NOTE 

When you run TNT, the status of the Transparent File Access utility is 
also reported. 

To invoke TNT, type the following command: 

E>TN : (RET) 

The system responds with a start-up message: 
Transparent Network Task Control VI . 1 

and one or more of the following status message(s): 
DECnet TTT is not installed. 
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DECnet TTT has no errors to report 



DECnet TTT Errors are: 

remote file specification: extended error message 



or 

DECnet TFA is not installed. 
DECnet TFA has no errors to report. 
DECnet TFA Errors are: 

remote file specification : extended error message 



where 

extended error message is a message contained in the external variable errno. See 
Appendix C for a list of errno messages. 

3.6.2 On-Line Help 

On-line help provides you with a list of supported TNT commands. To obtain help, 
type: 

e> ; ■ 



The system responds with the following help text: 

Transparent Network Task Control VI . 1 
Transparent Network Task commands are: 

TNT Display status of both TTT and TFA. 

TNT HELP Display this text. 

TNT TTT OFF Remove TTT from memory. 

TNT TFA OFF Remove TFA from memory. 

If you mistype a command, TNT responds with an error message and the list of sup- 
ported TNT commands: 

Transparent Network Task Control VI . 1 
Transparent Network Task command error. 
Transparent Network Task commands are: 

TNT Display status of both TTT and TFA. 

TNT HELP Display this text. 

TNT TTT OFF Remove TTT from memory. 

TNT TFA OFF Remove TFA from memory. 
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3.6.3 Deinstalling TTT 

You can remove TTT from memory. Enter the following command line: 

E>TNT TTT QFF fRET") 

The system responds with the following text: 

Transparent Network Task Control VI . 1 
The task was removed successfully. 

If TTT could not be removed, one of the following messages is displayed: 
Transparent Network Task Control VI . 1 

TTT cannot be removed because it is not installed or is not installed 
last . 

or if MS-DOS failed on the remove call, 

Transparent Network Task Control VI . 1 
The task could not be removed. 

NOTE 

TTT traps MS-DOS interrupt function call 21H as do other software 
applications. If you want to remove TTT from memory, it must be the 
last task installed which intercepts interrupt 21H. Otherwise, you 
must remove any tasks installed after TTT that also traps 21H, or 
reboot your system to remove TTT. 

3.7 TTT Programming Considerations 

There are specific MS-DOS function requests that support DECnet-DOS transparent 
task-to-task communication. Table 3-1 provides you with a summary of these calls. 
When creating TTT applications, you should note the following: 

• Some user programs may not accept the TTT network specification string. 

• You should not use unsupported MS-DOS function calls to perform transparent 
task-to-task communication. 

• If you issue a ictrl/c ) while TTT is active, network operation may be blocked. To 
clear this condition, run the TNT utility. 

3.8 MS-DOS Function Requests for Transparent Task-to-Task 
Communication 

The following sections describe the MS-DOS function requests and provide specific 
guidelines. A drawing of the 8086/8088 registers shows their contents before and after 
each function request. 

The function requests are discussed in alphabetical order. 



3-8 



DECnet-DOS Programmer's Reference Manual 



3.8.1 Close 
NAME 

Close - terminate a logical link connection and deactivate the original handle. 



+ + 

| On 8086/8088 Register Contents ] 
! Entry \ \ 
+ + + 

| AH | 3EH ! 

+ + + 

j BX i handle for logical link access ! 
+ + + 



+ ■ 

| On | 8086/8088 Register Contents 

| Return | 

+ + 

| AX | no errors; if carry bit is clear 

I I 

| | error code; if carry bit is set 

I I 

+ + 



Figure 3-1 : Close Function Request 
DESCRIPTION 

The Close function request terminates the logical link connection and deactivates the 
handle used for data exchange. Either task can issue the Close call. 

On entry, the BX register contains the 1 6-bit handle value returned by the open or cre- 
ate I/O operation. If the close operation completes successfully and the carry bit is 
clear, no error is returned in the AX register. If an error condition occurs and the carry 
bit is set, the appropriate error code is returned in the AX register. 

The following error code can occur: 
Hexadecimal 

Value Meaning 

6 An invalid handle value was detected. 
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3.8.2 Create/Open 
NAME 

Create/Open - initiate or accept a logical link connection request. 



On 

Entry 


1 


8086/8088 Register Contents 


AH 


1 


3CH or 3DH 


DS:DX 


- + ■ 

1 
1 


address of network task 
specification string 


AL 


1 

- + • 






+ + 

I On | 8086/8088 Register Contents 

| Return | I 

+ + + 

j AX | handle for logical link access; I 

I | if carry bit is clear I 

I I I 
j | error codes; if carry bit is set | 
+ + + 



Figure 3-2: Create/Open Function Request 
DESCRIPTION 

In the context of DECnet-DOS, the Create and Open calls perform the same functions. 
Either call can initiate and/or accept a logical link connection. However, if SYSSNETis 
specified as the node name in the network task specification, and supplied with either 
call, the function is only interpreted as the task accepting a logical link connection. 

• To initiate a logical link connection. The Create or Open call enables a source task 
to initiate a logical link connection. On entry, DS:DX contains the address of the 
network task specification string. Any optional access control information is 
passed as part of the string to the target task. 

On return, the AX register contains an error code or a 1 6-bit handle associated with 
the source task. The returned handle value must be used for subsequent read and 
write I/O operations. 
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• To accept a logical link connection. The Create or Open call accepts a logical link 
request from another network task. The 1 6-bit handle value is returned in the AX 
register. This handle must be used for subsequent read and write operations. On 
entry, DS:DX contains the address of the network task specification string. 

If you are unable to initiate a logical link connection, an error code is returned in the 
AX register. To obtain extended error information, run the TNT utility. 

The following error code can occur.- 

Hexadecimal 

Value Meaning 

2 The network process may not be loaded. The node name to node 

address mapping is not found in the database file. The target task 
on the outgoing connection is not available. The network is 
unreachable. Too many files are currently open. There is an error 
in the path specification string. 

The target task was not found. 

There are too many active logical link connections. 

The remote object rejected the request. 

If you are unable to accept a logical link connection, an error code is returned in the AX 
register. To obtain extended error information, run the TNT utility. 

The following error code can occur: 

Hexadecimal 

Value Meaning 

2 The target task was not found. 

Network access was denied. 
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3.8.3 Read 
NAME 

Read - receive data over a logical link connection. 



On 

Entry 


! 8086/8088 Register Contents 


AH 


| 3FH 


DS:DX 


- + 

| address of network message buffer 


CX 


- + 

| size of network message buffer 


BX 


| handle for logical link access 



+ + 

I On | 8086/8088 Register Contents | 

I Return | I 

+ + + 

| AX | number of bytes received over the ! 
I I logical link; carry bit | 
| I is clear | 
+ + I 



Figure 3-3: Read Function Request 
DESCRIPTION 

The Read function request allows the target task to receive data sent over the logical 
link. 

On entry, the BX register contains the 1 6-bit handle value. The CX register contains the 
number of bytes to be received. DS:DX contains the address of the network message 
buffer. 

On return, the AX register contains the number of bytes successfully received by the tar- 
get task. If an error condition occurs, zero bytes are returned. To obtain extended error 
information, run the TNT utility. See Appendix D for a list of extended error messages. 
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3.8.4 Write 
NAME 

Write - send data over a logical link connection. 



On 

Entry 


| 8086/8088 Register Contents 

1 


AH 


I 40H 


DS:DX 


| address of network message buffer 


CX 


| size of network message buffer 


BX 


| handle for logical link access 



On | 8086/8088 Register Contents 

Return j 



AX 



number of bytes sent over the 
logical link; if carry bit 
is clear 

error codes; if carry bit is set 



Figure 3-4: Write Function Request 



DESCRIPTION 

The Write function request allows the source task to send data over the logical link. 

On entry, the BX register contains the 1 6-bit handle value. The CX register contains the 
number of bytes to be sent. DS:DX contains the address of the network message buffer. 

On return, the AX register contains the number of bytes successfully sent by the source 
task. If an error condition occurs, the error code is returned in the AX register. To 
obtain extended error information, run the TNT utility. 

The following error code can occur: 
Hexadecimal 

Value Meaning 

5 Network access was denied. 
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4 

C Language 



DECnet-DOS includes C language source files which are used to create a linkable 
library for DECnet-DOS applications. This library provides compatibility with the net- 
work socket interface supported by DECnet-ULTRIX. 

4.1 Creating the DECnet-DOS Programming Interface Library 

The file DNETLIB.SRC contains three types of files: the .C files (C language sources), 
the .H files (header files that contain definitions for the network interface) and the 
.ASM files (assembly language sources). You should refer to the appropriate installation 
guide for a complete list of these files. 

In order to interface to the DECnet-DOS network process, you should create a library 
against which to link your DECnet-DOS program(s). 

Use the following procedure to create a DECnet-DOS programming interface library: 

1. The Break Source utility, BREAKSRC, allows you to break the source file, 
DNETLIB.SRC, into separate source files for compilation and assemblies. 
BREAKSRC is supplied with the DECnet-DOS distribution kit. When you run the 
DECnet-DOS Installation Procedure (DIP), you can select to have the 
DNETLIB.SRC file split into separate files. The BREAKSRC utility will then be run 
automatically for you. For instructions on how to run DIP, refer to the appropriate 
installation guide. 

To manually use BREAKSRC, follow this format: 

BREAKSRC < input file spec> < output device :\path> 

For example: 

BREAKSRC A:DNETLIB.SRC C:\DECNET\SRC\ 
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2 . Use your C language compiler to compile each C language source module. Use your 
assembler to assemble each assembly source module. 

3 . After you produce an object module for each source module, build a library against 
which to link your DECnet-DOS applications programs. 

4.1.1 DECnet-DOS Programming Considerations 

The following programming considerations should be noted when writing and devel- 
oping your DECnet-DOS applications: 

1. Using the External Variable errno - Most DECnet-DOS programming interface 
functions use the external variable errno as a place to return error detail. It is 
assumed that errno has been defined externally to the programming interface as an 
int. It may already be defined in your C language run-time library, if not, your appli- 
cations program should define it. 

Appendix C lists the error codes returned by DECnet-DOS in errno. 

2. Checking Software Compatibility - When creating DECnet-DOS applications, 
make sure that you resolve any C language compiler incompatibilities before com- 
piling the C language source modules such as long variable names or certain type 
definitions. 

3- Using Assembly Source Modules - There are assembly source modules included in 
DNETLIB.SRC. Before you can successfully call these functions from sources com- 
piled by your C language compiler, you should fulfill any assembly-format require- 
ments such as segment names. (Refer to the header file, begin. h, on the distribution 
kit as an example of specific C language compiler segment naming requirements.) 

4. Using Specific Macros - There are references to the macros/functions such as 
toupper and islower in some of the C language source modules. It is assumed that 
your C language compiler has provided a standard macro/function for them. If not, 
you can simply provide your own macros/functions. 

5. If you are not using a C compiler that supports the signal handling function (for 
example, (ctrl/c ) trapping), then you will need to either provide your own signal 

function or comment out from the code in dnet conn any references to the sig- 

nal( ) function and the reference to the include file, < signal. h > . 

The [ctrl/c ) trapping, provided in dnet conn, allows you to abort a utility which 

appears to be waiting indefinitely for connections to complete. (This applies only 

to utilities that use dnet conn for making connections.) The connect function in 

dnet conn is invoked in a nonblocking socket mode. 

If i ctrl/c ) trapping code is commented out from dnet conn, there is the potential 

problem of leaving hung sockets and running out of system resources, should users 
decide to [ctrl/c ] in the middle of nonblocking connection request attempts. 
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6. If you are using a compiler that does not define the following variables: int day- 
light, long timezone and char *tzname[2], either comment these external declara- 
tions out of the header file < time.h > or define them in your C program code. 

7 . The DECnet-DOS programming interface library was based on a 2-segment model. 

Caution 

If a program terminates with any active logical links (sockets), the links 
remain active. In this way, another program can start and use the same 
links. 

If the logical links are not needed, you must issue an sclose function 
call before a program is terminated with an EXIT, [ctrl/z ) or (ctrl/c I . If 
too many links are left active, an error message, indicating that no 
more buffers are available or insufficient network resources, is 
reported. This causes the network to become unusable. To completely 
deactivate any logical links, run the Network Control Program (NCP) 
and issue the SET KNOWN LINKS command with STATE OFF. (See the 
DECnet-DOS User's Guide for more information on this command.) 



4.2 How to Read the Socket I nterf ace Call Descriptions 



The socket interface calls are presented as separate entries in this manual. They are 
documented in a consistent manner. Each call is described under the following head- 
ings: 



NAME 
SYNTAX 

DESCRIPTION 

DIAGNOSTICS 



gives the exact name and a brief description of its function. 

shows the complete syntax. Possible call options and the 
type of expected argument(s) are indicated. 

provides more detail on what the call does, and how its 
action is modified by the options. 

gives explanations of error messages that may be produced. 



4.3 Understanding a SYNTAX Section 

Each socket interface call documented in this chapter has a SYNTAX entry. It shows 
how a call is defined. The SYNTAX entry consists of several components. 

The SYNTAX section for the bind call illustrates these components: 

int bind(s, name, namelen) 

int s, namelen; 

struct sockaddr dn *name; 
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The first line represents the function call and a list of input arguments. Each function 
call should do one specific task. Data may be passed to the called function via argu- 
ments. The input arguments follow the function name. They are separated by commas 
and surrounded by parenthesis. 

The next set of lines list the formal arguments and their respective data types (char, int 
or structure). 

Using the bind call example, *name declares name to be a pointer to the structure type 
sockaddr_dn. This structure contains several modifiable fields. 
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4.4 Socket Function Calls 

The following sections describe the socket interface function calls for C programs. 
They also provide you with specific guidelines. Some of the socket interface calls use 
specific data structures. Appendix B details how each data structure is formatted. 

The socket interface calls are summarized in the table below: 

Table 4-1 : Socket Interface Calls 



Socket Call Description 

accept Accept an incoming connection request on a socket, and return a 
socket number. 

bind Assign an object name or number to a socket. 

connect Initiate a connection request on a socket. 

getpeername Get the name of a connected peer on a socket. 

getsockname Get the current name for the specified socket. 

getsockopt Get options associated with sockets. 

listen Listen for pending connections on a socket. 

recv Receive data and out-of-band messages on a socket. 

sclose Terminate a logical link connection and deactivate a socket. 

select Check the I/O status of the network sockets. 

send Send data and out-of-band messages on a socket. 

setsockopt Set options associated with sockets. 

shutdown Shutdown part or all of a full duplex logical link connection, 

sioctl Control the operations of sockets. 

socket Create an endpoint for communication and return a socket number, 

sread Read data on a socket, 

s write Write data to a socket. 
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4.4.1 Example Socket Interface Calling Sequence 

The following program segments illustrate the socket interface calls used by DECnet- 
DOS client and server tasks. 



Socket calls 


issued by a client 


ta 


s k : 




s = socketC.. 


. ) 




/* 


get a DECnet socket 


*/ 


setsockopt ( s , 


, D S 0_C0N D A T A , , ) 




/* 


set up optional data 


*/ 


setsockopt ( s , 


, DS0_C0NACCESS , 


, ) 


/* 


set up access- 


*/ 










control information 


* / 


connectts, . • • 


) 




/ * 


initiate connection to 


* / 










the server task 


* / 


getsockoptcs # 


,DS0_C0NDATA , , ) 




/ * 


get returned status and 


+ / 








/ * 


optional data 




send( s , . . . ) 








send data (or write) 


* / 


r e c v ( s , . . . ) 






/ * 


1 t? 1* c 1 v c U d l d \ U 1 1 c d U / 




setsockopt(s, 


, DS0_D I SDATA ) 






set up optional 










/ * 


data "for disconnect 


* / 


sclose(s) 






i * 


terminate connection 


* / 


Socket calls 


issued by a server 


t a 


s k : 




s = s o c k e t ( . . 


. ) 




/ * 


get a DECnet socket 


* / 


b i nd ( s , . . . ) 






/ * 


bind a name to the socket 




listen(s,...) 






/ * 


ill a M: L II c oUulstrL avdlldUlc 










/ * 


f n r c 1 lont rr\nncsri'irinc 
IUI I* I. 1 CM L l> U 1 1 1 1 tr v* I lUlIb 




setsockopt(s. 


, DS0_ACCM0DE , 




/ * 


accept m od 6 i 


* 1 


ACC_DE FER , ) 




/ * 


ci(*'fp*rr % pri / i mmpHi a t p 
vj ~ i c i i c u / i hi in c \j i a x. c 


* / 


ns = acceptCs 


, . . . ) 




/* 


await connect(s) on the 


*/ 








/* 


new socket, ns 


*/ 


getsockopt(ns 


, , DS0_C0NACCESS , , ) 


/* 


get access 


*/ 








/* 


control information 


*/ 


getsockopt(ns 


, , DS0_C0N D AT A , , 


) 


/* 


get optional connect data 


*/ 


setsockopt ( ns 


, , DS0_C0N DAT A , , 


) 


/* 


set up optional data 


*/ 


setsockopt ( ns 


, , DS0_C0NACCEPT , , ) 


/* 


finally accept the 


*/ 








/* 


connection request 


★/ 


recvtns, . , . ) 






/* 


receive data (or read) 


*/ 


s end ( ns , . . . ) 






/* 


send data (or write) 


*/ 


setsockopt ( ns 


, , DS0_DI SDATA , , 


) 


/* 


set up optional 


*/ 








/* 


disconnect data 


*/ 


sclose(ns) 






/* 


terminate connection 


*/ 


s c I os e ( s ) 






/* 


terminate DECnet path 


*/ 
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4.4.2 accept 
NAME 

accept - accept an incoming connection request on a socket and return a socket num- 
ber. 

SYNTAX 

#include < types. h> 
#include < socket. h> 
#include <dn.h> 

int accept(s, sorcblk, sorclen) 

int s, * sorclen; 

struct sockaddr dn * sorcblk; 

DESCRIPTION 

The accept call extracts the first connection request on the queue of pending connec- 
tions, creates a new socket with a new number having the same properties of the origi- 
nal listening socket. The original socket remains opened. 

If the socket is set to nonblocking I/O, and there are no queued connection requests, 
io status will return a -1 and errno will contain EWOULBLOCK. 

There are two modes of accepting an incoming connection. They are immediate and 
deferred modes. These modes of acceptance are set via the setsockopt call. When imme- 
diate mode is in effect, the connection is established immediately. The deferred mode 
indicates that the server task completes the accept call without fully completing the 
connection to the client task. In this case, the server task can examine the access con- 
trol or optional data before it decides to accept or reject the connection request. The 
server task can then issue the setsockopt call with the appropriate reject or accept 
option. 

Input Arguments 

5 specifies the number for a socket which was created with the socket 

call, bound to a name or number by the bind call, and was set to listen 
for connects by the listen call. 

sorcblk is a value result argument. It specifies an address of a structure sorcblk 

of the data type sockaddr_dn. This argument will be filled in with 
the information of the entity requesting the connection. 

sorclen is a value result argument. It specifies the address of an int. The value 

of sorclen should initially contain the size of the sorcblk. 
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Return Arguments 

sorclen specifies the actual length of the returned data in bytes. 



sorcblk 



specifies the socket address data structure, sockaddr_dn. A user 
retrieves data from the fields filled in by this function call. (See Appen- 
dix B on how sockaddr_dn is formatted.) 



The following data fields are filled in by this function call: 



sdn__family 
sdn objnum 

sdn objnamel 

sdn objname 

sdn add 

Return Value 



is the address family AF DECnet. 

is the object number for the client task. It can be a number 
to 255. It is set to only when the object name is used. 

is the size of the object name. 

is the object name of the client task. It can be up to a 16-ele- 

ment array of char. It is used only when sdn objnum equals 

0. 

is the node address structure for the client task. (See Appen- 
dix B on how dn naddr is formatted.) 



If the call succeeds, it returns a nonnegative integer called a socket number. This num- 
ber will be used for communications over a logical link connection. If an error occurs, 
the call returns a -1. When an error condition exists, the external variable errno will 
contain error detail. See the DIAGNOSTICS section for a full description of the error 
messages. 



DIAGNOSTICS 

[EBADF] 

[ECONNABORTED] 

[ENETUNREACH] 

[ENFILE] 

[EWOULDBLOCK] 



The argument s does not contain a valid socket number. 

The client task disconnected before the accept call com- 
pleted. 

The network is unreachable. The network process is not 
installed. 

There are no more available sockets. 

The socket is marked for nonblocking and no connections 
are waiting to be accepted. 
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4.4.3 bind 



NAME 

bind - assign an object name or number to a socket. 
SYNTAX 

#include <types.h> 
#include < socket. h> 
#include <dn.h> 

int bind(s, name, namelen) 

int s, namelen; 

struct sockaddr dn *name; 

DESCRIPTION 

The bind call assigns an object name or number to a socket. When a socket is first cre- 
ated with the socket call, it exists in a name space but has no assigned name or number. 
The bind call is used primarily by server tasks. The object name is required before a 
server task can listen for incoming connection requests using the listen call. It can also 
be used by client tasks to identify themselves to server tasks. See also the accept (Sec- 
tion 4.4.2), connect, (Section 4.4.4), getpeername (Section 4.4.5), and getsockname 
(Section 4.4.6) calls. 

NOTE 

VAX/VMS proxy access by user name is made possible if the client task 
uses the bind call specifying his user name as the object name. Refer to 

the SO REUSEADDR option for the setsockopt call (Section 4.4. 12) if 

you want to make more than one proxy connection with the same 
name. 

Input Arguments 

5 specifies the number for a socket which has been created with the socket 

call. 

name specifies the address of the structure name of data type sockaddr _dn. A 

user fills in the data for each field. (See Appendix B on how sockaddr __dn 
is formatted.) 

The following data fields can be modified: 

sdn_family specifies the address family as AF DECnet. 

sdn_flags specifies the object flag option. It must be set to 0. 

sdn objnum defines the object number for the server task. It can be a number 

to 255 - It is set to only when the object name is used. 
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sdn objnamel 

sdn_objname 

sdn_add 



is the size of the object name. 

defines the object name of the server or client task. It can be up 
to a 16-element array of char. It is used only when 
sdn_objnum equals 0. 

specifies the node address structure for the server task. This 
data member is ignored. 



namelen specifies the size of the name structure. 

Return Value 

If the bind is successful, a value is returned. An unsuccessful bind returns a value of 
-1. When an error condition exists, the external variable errno will contain error 
detail. 



DIAGNOSTICS 

[EADDRINUSE] 

[EBADF] 

[EINVAL] 

[ENETUNREACH] 



The specified name or number is already used by another 
socket. 

The argument 5 does not contain a valid socket number. 

The socket s is already bound to a name or number. 

The network is unreachable. The network process is not 
installed. 
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4.4.4 connect 
NAME 

connect - initiate a connection request on a socket. 
SYNTAX 

#include <types.h> 
#include < socket. h> 
#include <dn.h> 

int connects, destblk, destlen) 

int s, destlen; 

struct sockaddr dn, * destblk; 

DESCRIPTION 

The connect call issues a connection request to another socket. The other socket is spec- 
ified by destblk which is a pointer to the destblk data structure. 

Optional data as well as access control information may be passed with this function 
call. This data must be previously set by the setsockopt call. If subsequent connect calls 
are issued on the same socket, a task must reissue the setsockopt call to set up new 
optional user data and/or access control information. 

Input Arguments 

5 specifies the number for the socket which has been created with the 

socket call. This socket number is used for establishing a connection 
between the user tasks. It is also used with subsequent send and receive 
function calls. 

destblk specifies the address of the structure destblk of the data type 

sockaddr _dn. A user fills in the data for each field. (See Appendix B on 
how sockaddr_dn is formatted.) 

The following data fields can be modified: 

sdn_family specifies the address family as AF DECnet. 

sdn_flags specifies the object flag option. It must be set to . 

sdn objnum defines the object number for the server task. It can be a num- 

ber to 255. 

sdn objnamel is the size of the object name. 

sdn_objname defines the object name of the server task. It can be up to a 

16-element array of char. It is used only when sdn objnum 

equals 0. 

sdn add specifies the node address structure for the server task. (See 

Appendix B on how dn_naddr is formatted.) 

destlen specifies the size of the destination block structure. 
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Return Value 



If the call succeeds, it returns a value of 0. Otherwise, the call returns a value of -1. 
When an error condition exists, the external variable errno will contain error detail. If 
the socket is set to nonblocking I/O (see also sioctl, Section 4 .4. 14), and you issue a con- 
nect, the function returns a -1, and the error message, EINPROGRESS. 

DIAGNOSTICS 



[EAFNOSUPPORT] 

[EBADF] 

[EBUSY] 

[ECONNABORTED] 

[ECONNREFUSED] 

[ECONNRESET] 

[EHOSTUNREACH] 

[EINPROGRESS] 

[ENETDOWN] 

[ENETUNREACH] 

[ERANGE] 

[ESRCH] 
[ETIMEDOUT] 

[ETOOMANYREFS] 



Addresses in the specified address family cannot be 
used with this particular socket. 

The argument 5 does not contain a valid socket num- 
ber. 

The socket is not in idle state. The socket is in the pro- 
cess of being connected or disconnected; is currently 
a connected or listening socket. 

The peer task has disconnected and the connection 
was aborted. 

The attempt to connect was forcefully rejected. 

The remote task has failed. 

The remote node is unreachable. 

The connection request is now in progress. 

The network is down. The Executor name and 
address may not have been set and/or the Executor 
state may not have been set ON. 

The network is unreachable. The network process is 
not installed. 

The object number of the server task is invalid. The 
valid range is to 255. 

The server object does not exist on the remote node. 

Connection establishment was timed out before a 
connection was established. 

The remote node has accepted the maximum num- 
ber of connection requests. 
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4.4.5 getpeername 
NAME 

getpeername - get the name of a connected peer on a socket. 
SYNTAX 

#include <types.h> 
#include <socket.h> 
#include <dn.h> 

int getpeername(s, destblk,destlen) 

int s, *destlen; 

struct sockaddr dn *destblk; 

DESCRIPTION 

The getpeername call returns information about the peer socket connected to the speci- 
fied socket. This information is the same information returned by the accept call. It 
may be used by a client or server task anytime after a connection has been established 
between two tasks or peers. 

Input Arguments 

5 specifies the number for a socket which has been created by the socket or 

the accept call. 

destblk specifies the address of the destblk structure of the data type 
sockaddr _dn. This argument will be filled in with peer information 
returned by getpeername. 

destlen is a value result argument. It specifies the address of an int. The value of 
destlen should be initialized to the size of the destblk. 

Return Arguments 

destlen specifies the actual size of the destination block (in bytes). 

destblk specifies the socket address data structure, sockaddr_dn. A user 
retrieves data from the fields filled in by this function call. (See Appendix 
B on how sockaddr__dn is formatted.) 

The following data fields can be filled in by this function call: 

sdn_family is the address family AF DECnet. 

sdn_objnum is the object number for the peer task. It can be a number to 
255. 

sdn objnamel is the size of the object name. 

sdn objname is the object name of the peer task. It can be up to a 16-element 

array of char. It is only used when sdn objnum equals 0. 
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sdn_add is the address structure for the peer node . (See Appendix B on 
how dn naddr is formatted.) 

Return Value 

If the call succeeds, a value of is returned. If an error occurs, the call returns a -1. 
When an error condition exists, the external variable errno will contain error detail. 
See the DIAGNOSTICS section for a full description of the error messages. 

DIAGNOSTICS 

[EBADF] The argument 5 does not contain a valid socket number. 

[ENETUNREACH] The network is unreachable. The network process is not 

installed. 

[ENOTCONN] The socket 5 is not connected, it has no peer. 
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4.4.6 getsockname 
NAME 

getsockname - get the current object name or number for the specified socket. 
SYNTAX 

#include < types. h> 
#include < socket. h> 
#include <dn.h> 

int getsockname(s, destblk, destlen) 

int s, "destlen; 

struct sockaddr dn * destblk; 

DESCRIPTION 

The getsockname call returns the bound object name or number of the specified 
socket. 

Input Arguments 

5 specifies the number for a socket which has been created by the socket 

or the accept call. 

destblk specifies the address of a structure of the data type sockaddr _dn. 

This argument will be filled in with local task information returned by 
getsockname. 

destlen is a value result argument. It specifies the address of an int. The value 

of destlen should be initialized to the size of the destblk. 

Return Arguments 

destlen specifies the actual size of the destination block (in bytes). 

destblk specifies the socket address data structure, sockaddr _dn. A user 

retrieves data from the fields filled in by this function call. (See Appen- 
dix B on how sockaddr_dn is formatted.) 

The following data fields can be filled in by this function call: 

sdn_family is the address family AF DECnet. 

sdn objnum is the object number for the local task. It can be a number to 

255. 

sdn objnamel is the size of the object name. 

sdn objname is the object name of the local task. It can be up to a 1 6-element 

array of char. It is only used when sdn objnum equals 0. 

sdn add is the address structure for the local node. (See Appendix B on 

how dn naddr is formatted.) 
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Return Value 

If the call succeeds, a value of is returned. If an error occurs, the call returns a -1. 
When an error condition exists, the external variable errno will contain error detail. 
See the DIAGNOSTICS section for a full description of the error messages. 

DIAGNOSTICS 

[EBADF] The argument s does not contain a valid socket number. 

[ENETUNREACH] The network is unreachable. The network process is not 

installed. 
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4.4.7 listen 
NAME 

listen - listen for pending connections on a socket. 
SYNTAX 

int listen(s, backlog) 

int s; 

int backlog; 

DESCRIPTION 

The listen call declares your socket as a server which is available for client connections. 
The server uses the bound name or number in order to listen for incoming client con- 
nections. This call must be issued before an incoming connection can be accepted or 
rejected. See also the accept (Section 4.4.2), the bind (Section 4.4.3) and the select (Sec- 
tion 4.4. 10) calls. 

If you detach a listening socket while the socket is receiving client connections, then all 
links associated with the listening socket immediately abort and all outstanding data is 
lost. 

Input Arguments 

5 specifies the number for a socket which has been created with the socket 

call and bound to a name or number by the bind call. 

backlog defines the maximum number of unaccepted incoming connects which 
are allowed on this particular socket. The maximum allowable number is 
5. If a connection request arrives when the queue is full, the client task 
will receive an error with an indication of ECONNREFUSED. 

Return Value 

If the call succeeds, a value of is returned. If an error occurs, the call returns a -1. 
When an error condition exists, the external variable errno will contain error detail. 
See the DIAGNOSTICS section for a full description of the error messages. 

DIAGNOSTICS 

[EBADF] The argument s does not contain a valid socket number. 

[ECONNREFUSED] The connection request was rejected. 

[ENETUNREACH] The network is unreachable. The network process is not 
installed. 

[EOPNOTSUPP] The socket type does not support the listen operation. 
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NOTE 



You may issue a listen(s, 0) call while already processing data over a 
previously accepted connected socket. If this is done, subsequent 
incoming connection requests will be rejected by the network process. 
When communications are completed over the currently connected 
socket, the listen(s, backlog) call should be reissued to allow for subse- 
quent acceptance of incoming connection requests. 
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4.4.8 recv 
NAME 

recv - receive data or out-of-band messages on a socket. 
SYNTAX 

#include < socket. h> 

int recv(s, buffer, buflen, flags) 
int s, buflen, flags; 
char * buffer; 

DESCRIPTION 

The recv call is used to receive data from your peer. See also the sread call (Section 
4.4.16). 

If no messages are available at the socket, the recv call waits for a message to arrive 
unless the socket is nonblocking. (See sioctl, Section 4.4. 14). In this case, a status of -1 
is returned with the external variable errno set to EWOULDBLOCK. 

If the link is disconnected, queued data can still be received on the socket. However, if 
you shutdown the socket or detach it, queued data cannot be received. When the logi- 
cal link is not in a connected state, and all data has been read, the recv call returns zero 
bytes. 

The select call may be used to determine when more data has arrived. (See Section 
4.4.10) 

Out-of-band messages are delivered to a receiving task ahead of normal data messages. 
These messages can be received by specifying MSG OOB as the flag argument. 

Input Arguments 

5 specifies the number for a socket returned by the socket or the accept call. 

buffer specifies the address of a buffer which will contain the received message. 

buflen specifies the size of the message buffer. 

flags set to indicates that the task will receive normal messages. If set to 
MSG OOB, the task will receive out-of-band messages. Only one out-of- 
band message can be outstanding at any time. You can also set the flags 
argument to MSG_PEEK to read the next pending message without 
removing it from the receive queue. 

Output Argument 

buffer specifies the buffer which contains the received message. 
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Return Value 



If the call succeeds, the number of received characters are returned. 



If the call returns a zero, you have either received a zero length message or the logical 
link has been disconnected. To determine the state of the logical link, use the 

getsockopt function call with the DSO LINKINFO option (See Section 4.4. 12), or the 

DECnet utility function, dnet eo/(See Chapter 5). If the link has been disconnected, 

then all subsequent receives will return zero bytes. 

If an error occurs, a value of -1 is returned. Additional error detail will be specified in 
the external variable errno. See the DIAGNOSTICS section for a full description of the 
error messages. 

DIAGNOSTICS 

When receiving normal data, the following set of error messages can occur: 
Blocking I/O 

Description 

The argument 5 does not contain a valid socket number. 



Message 

[EBADF] 
[ENETUNREACH] 



Nonblocking I/O 
Message 

[EBADF] 

[ENETUNREACH] 
[EWOULDBLOCK] 



The network is unreachable. The network process is not 
installed. 



Description 

The argument 5 does not contain a valid socket number. 

The network is unreachable. The network process is not 
installed. 

The receive operation would block because there is cur- 
rently no data to receive. 



When receiving out-of-band data, the following set of error messages can occur: 
Blocking I/O 

Description 

The argument 5 does not contain a valid socket number. 



Message 

[EBADF] 
[ENETUNREACH] 



[EWOULDBLOCK] 



The network is unreachable. The network process is not 
installed. 

The receive operation would block because there is cur- 
rently no data to receive. 
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Nonblocking I/O 

Message Description 

[EBADF] The argument 5 does not contain a valid socket number. 

[ENETUNREACH] The network is unreachable. The network process is not 

installed. 

[EWOULDBLOCK] The receive operation would block because there is cur- 

rently no data to receive. 
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4.4.9 sclose 
NAME 

sclose - terminate a logical link connection and deactivate a socket. 

SYNTAX 

int sclose(s) 
int s; 

DESCRIPTION 

The sclose call terminates an outstanding connection over the socket referenced by 5. It 
also deactivates the socket. 

NOTE 

Before you can terminate a connection over a socket set with the 

option SO KEEPALIVE, you must first issue a setsockopt call with the 

SO KEEPALIVE option turned off. That is, precede the 

SO_KEEPALIVE with a "(tilde), as in SO KEEPALIVE. Then issue the 

sclose function call and the connection is completely broken. 

The effect of sclose on unsent data queued for a remote task depends on the linger 

option set with the setsockopt function call. (See Section 4. 4. 12.) If SO LINGER is set, 

control is returned to the task, but the link is not disconnected until the unqueued data 

is sent. If SO DONTLINGER is set, control is returned to the task, and any unqueued 

data is lost. 

NOTE 

The DECnet-DOS function call sclose is not compatible with DECnet- 
ULTRIX systems. See Appendix G for information on how to transport 
DECnet-DOS programs that use sclose. 

Input Argument 

5 specifies the number for a socket which was returned by the socket or the 

accept call. 

Return Value 

If the call succeeds, a value of is returned. If an error occurs, a value of - 1 is returned. 
Additional error detail will be specified in the external variable errno. See the DIAG- 
NOSTICS section for a full description of the error messages. 

DIAGNOSTICS 

[EBADF] The argument 5 does not contain a valid socket number. 

[ENETUNREACH] The network is unreachable. The network process is not 
installed. 
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4.4.10 select 
NAME 

select - check the I/O status of the network sockets. 
SYNTAX 

#include <time.h> 



int select(nfds, readfds, writefds, exceptfds, timeout) 

int nfds; 

unsigned long * readfds, * writefds, * exceptfds; 

struct timeval 'timeout; 



DESCRIPTION 

The select call checks the network sockets specified by the bit masks readfds, writefds, 
and exceptfds, respectively, to see if they are ready for reading, writing, or have any 
outstanding out-of-band messages. The select call does not tell you if the logical link 
connection has been broken. 

You should use the select call to help manage your accept, send, recv, swrite, and sread 
calls. 

The readfds, writefds, and exceptfds I/O descriptors are long words which contain bit 
masks. Each bit in a mask represents one socket number. For example, socket "3" is the 
fourth bit or has a hex value of 8. 

NOTE 

The select call can only check socket numbers in the range to 3 1 . 

To specify the bit for any socket number, use the value returned by the socket or the 
accept call, as " 1< < 5" . 

Input Arguments 

nfds specifies the highest socket number to be checked. The bits from 

(1< < 0) to (1< < (nfds-1)) are examined. 

readfds specifies the socket numbers to be examined for read ready. For listen- 

ing sockets, a read ready condition indicates that an incoming connec- 
tion request can be read and either accepted or rejected. For 
sequenced sockets, there is a complete message to be read. For stream 
sockets, there is some data to be read. If a socket disconnects or 
aborts, a read ready condition will always occur. 

NOTE 

To prevent a program from hanging on a stream 
socket, issue the sioctl call, with the FIONREAD func- 
tion argument (See Section 4.4.14), and then read 
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only those number of bytes returned by the call. You 
should also perform socket operations in 
nonblocking I/O mode. 

This descriptor can be given as a null pointer if of no 
interest. 

writefds specifies the socket numbers to be examined for write ready. A write 

ready condition exists when the logical link is available. This descrip- 
tor can be passed as a null pointer if of no interest. 

exceptfds specifies the socket numbers to be examined for out-of-band data 

ready. There is a pending out-of-band message to receive . This descrip- 
tor can be given as a null pointer if of no interest. 

NOTE 

The bit mask exceptfds is presently not supported by 
DECnet-ULTRIX. 

timeout specifies a pointer to a data structure of type timeval. If this pointer is 

null, then the select call will wait until an event occurs. If the pointer is 
non-null, and the time value is greater than zero, then the select call 
will return either after n seconds have expired or when an event 
occurs, whichever one comes first. If the pointer is non-null and the 
time value is zero, then the select call will return after an immediate 
poll. 

timeval specifies the amount of time to wait. The data members are: 

tv sec specifies the time in seconds. 

tv usee this data member is ignored. 

Output Arguments 

read_fds If a socket is read ready, the bit is returned "on", and read_fds 

returns the socket numbers (as bit masks) to be examined. If the 
socket is not read ready, the bit is cleared. 

write_fds If a socket is write ready, the bit is returned "on", and write _fds 

returns the socket numbers (as bit masks) to be examined. If the 
socket is not write ready, the bit is cleared. 

except_fds If the socket is out-of-band data ready, the bit is returned "on", and 
except_fds returns the socket numbers (as bit masks) to be exam- 
ined. If the socket is not out-of-band data ready, the bit is cleared. 
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Return Value 



The value returned by the select call is the number of bits set in all the masks. The bit 
masks contain the set bits that correspond to the sockets in which events have 
occurred. If the time period expires, a value of is returned. 

If an error occurs, a value of -1 is returned. Additional error detail will be contained in 
the external variable errno. See the DIAGNOSTICS section for a full description of the 
error messages. 



DIAGNOSTICS 



[EBADF] 

[ENETUNREACH] 



One of the specified bit masks is an invalid descriptor. 

The network is unreachable. The network process is not 
installed. 
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4.4.11 send 
NAME 

send - send data or out-of-band messages on a socket. 
SYNTAX 

#include < socket. h> 

int send(s, buffer, buflen, flags) 

int s, buflen, flags; 

char * buffer; 

DESCRIPTION 

The send call is used to transmit data to your peer. The client task uses the socket num- 
ber returned by the socket call. The server task uses the socket number returned by the 
accept call. 

If you cannot get enough buffer space while building the outgoing message on a block- 
ing socket, the message is blocked. You must wait until current transmissions are fin- 
ished. For a nonblocking socket, the error message, EWOULDBLOCK, is returned. If a 
socket disconnects, any outstanding data to be sent is discarded. 

The flag option, MSG OOB, can be set to indicate that out-of-band data will be sent to 

your peer socket. An out-of-band message is a high priority message that you can send 
to your peer. This message bypasses any normal messages waiting to be received. An 
out-of-band message must be received by your peer before another message can be 
sent. 

The select call can be used to determine if it is possible to send more data. (See Section 
4.4.10) 

Input Arguments 

s specifies the number for a socket returned by the socket or the accept call . 

buffer specifies the address of the buffer which contains the outgoing message. 

buflen specifies the size of the outgoing message. 

flags can be set to to indicate normal messages. It can be set to MSG OOB 

for out-of-band messages. 

Return Value 

If the call succeeds, the number characters sent is returned. If an error occurs, a value of 
-1 is returned. Additional error detail will be specified in the external variable errno. 
See the DIAGNOSTICS section for a full description of the error messages. 
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DIAGNOSTICS 

When sending normal data, the following set of error messages can occur: 
Blocking I/O 

Description 

The argument s does not contain a valid socket number. 
The size of the outgoing message is more than 2048 bytes. 



Message 

[EBADF] 
[EMSGSIZE] 
[ENETUNREACH] 



[ENOTCONN] 
[EPIPE] 

Nonblocking I/O 
Message 

[EBADF] 

[EMSGSIZE] 

[ENETUNREACH] 

[ENOTCONN] 

[EPIPE] 

[EWOULDBLOCK] 



The network is unreachable. The network process is not 
installed. 

The send call did not complete and the link was discon- 
nected. 

The link has been disconnected, aborted or shutdown. No 
further messages can be sent. 



Description 

The argument 5 does not contain a valid socket number. 

The size of the outgoing message is more than 2048 bytes. 

The network is unreachable. The network process is not 
installed. 

The send call did not complete and the link was discon- 
nected. 

The link has been disconnected, aborted or shutdown. No 
further messages can be sent. 

The outbound quota was full, and the message could not be 
sent. Try again later. 



When sending out-of-band data, the following set of error messages can occur: 
Blocking I/O 

Description 



Message 

[EALREADY] 

[EBADF] 

[EMSGSIZE] 

[ENETUNREACH] 



The out-of-band message could not be sent. A similar trans- 
mission request is still in progress. 

The argument 5 does not contain a valid socket number. 

The size of the outgoing message is more than 16 bytes. 

The network is unreachable. The network process is not 
installed. 
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Message 

[ENOTCONN] 

[EPIPE] 

Nonblocking I/O 
Message 

[EALREADY] 

[EBADF] 

[EMSGSIZE] 

[ENETUNREACH] 

[ENOTCONN] 

[EPIPE] 



Description 

The send call did not complete and the link was discon- 
nected. 

The link has been disconnected, aborted or shutdown. No 
further messages can be sent. 



Description 

The out-of-band message could not be sent. A similar trans- 
mission request is still in progress. 

The argument 5 does not contain a valid socket number. 

The size of the outgoing message is more than 16 bytes. 

The network is unreachable. The network process is not 
installed. 

The send call did not complete and the link was discon- 
nected. 

The link has been disconnected, aborted or shutdown. No 
further messages can be sent. 
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4.4.12 setsockopt and getsockopt 
NAME 

setsockopt and getsockopt - set and get the options associated with sockets. 
SYNTAX 

#include <types.h> 
#include <socket.h> 
#include <dn.h> 

int setsockopt(s, level, optname, optval, optlen) 
int s, level, optname, optlen; 

char * optval; 

int getsockopt(s, level, optname, optval, optlen) 

int s, level optname, *optlen; 

char *optval; 

DESCRIPTION 

The setsockopt and getsockopt calls manipulate various options associated with a 
socket. Options exist at multiple levels and you must specify the level number for the 
desired operation. 

At the socket level (SOL_SOCKET), the options include: 

• SO KEEP ALIVE. If this option is set on a socket, any links and sockets associated 

with this socket will remain active, despite any attempts to disconnect them. 

NOTE 

Before you can terminate a connection over a socket with the 

option SO KEEP ALIVE set, you must first issue a setsockopt call 

with SO_KEEP ALIVE turned off. To turn off SO_KEEP ALIVE, 

you must precede SO KEEP ALIVE with a tilde " (as in, 

SO. KEEP ALIVE). ( ~SO_KEEPALIVE is the default condition.) 

You then issue the sclose call. The logical links (if any) are discon- 
nected, and the socket and associated sockets (if any) are 
deallocated. However, if you issue sclose without turning off 

SO KEEPALIVE, the sockets remain allocated, and the links (if 

any) stay active. 

• SO LINGER. SO LINGER controls the actions taken when unsent messages are 

queued on a socket and a sclose call is issued. If SO LINGER is set, the connection 

is maintained until the outstanding messages have been sent. This is the default con- 
dition. 
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• SO DONTLINGER. SO DONTLINGER also controls the actions of unsent mes- 
sages. If SO DONTLINGER is set, and the sclose call is issued, any outstanding mes- 
sages queued to be sent will be lost. The connection is then terminated. 

• SO REUSEADDR. SO REUSEADDR allows the reuse of a name already bound 

to a socket. For most situations, a name is bound to a socket only once. However, 
this option enables you to reuse the same name. This particular option must only 
be used for outgoing connection requests. It cannot be used for incoming connec- 
tions. 

At the DECnet level (DNPROTO NSP), socket options may specify the way in which a 

connection request is accepted/rejected, may be used to set up optional user data and/ 
or access control information, or may be used to obtain current link state information. 
The following socket options can be specified: 

• DSO ACCEPTMODE. The accept option mode is used at the DECnet level for pro- 
cessing accept calls. A socket must be bound (See Section 4.4.3) before specifying 
this option. There are two values which can be supplied for this option. They are 
immediate mode, ACC IMMED, and deferred mode, ACC DEFER. 

- ACC IMMED. ACC IMMED mode is the default condition for this option. 

When immediate mode is in effect, control is immediately returned to the 
server task following an accept call with the connection request accepted. The 
access control information and/or optional data is ignored by the server task. 

- ACC DEFER. ACC DEFER mode enables the server task to complete the 

accept call without fully completing the connection to the client task. In this 
case, the server task can examine the access control or optional data before it 
decides to accept or reject the connection request. The server task can then 
issue the setsockopt call with the appropriate reject or accept option. 

• DSO_CONACCEPT. DSO_CONACCEPT allows the server task to accept the 
pending connection on the socket returned by the accept call. The original listen- 
ing socket was set to deferred accept mode. Any optional data previously set by 
DSO CONDATA will also be sent. 

• DSO_CONREJECT. DSO_CONREJECT allows the server task to reject the pend- 
ing connection on the socket returned by the accept call. The original listening 
socket was set to deferred accept mode. Any optional data previously set by 

DSO DISDATA will also be sent. The reject reason is the value passed with this 

option. 

• DSO CO N DATA . DSO CONDATA allows up to 16 bytes of optional user data to 

be set by the setsockopt call. It can be sent as a result of the connect or the accept 
(with the deferred option) calls. The optional data is passed in a structure of type 
optdata_dn. (See Appendix B on how optdata_dn is formatted.) The data is read 
by the task issuing the getsockopt call with this option. 
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• DSO DISDATA. DSO DISDATA allows up to 16 bytes of optional data to be set 

by the setsockopt call. It can be sent as a result of the sclose call. The optional data is 
passed in a structure of type optdata__dn. (See Appendix B on how optdata_dn is 
formatted.) The data is read by the task issuing the getsockopt call with this option. 

• DSO_CONACCESS. DSO_CONACCESS allows access control information to be 
passed by the user task. This information is set with the setsockopt call. The access 
data is sent to the server task. It is passed with the connect call in a structure of type 
accessdata__dn. (See Appendix B on how accessdata_dn is formatted.) The 
access data is read by the task issuing the getsockopt call with this option. 

• DSO_LINKINFO. DSO_LINKINFO determines the state of the logical link con- 
nection. 

When the getsockopt call is issued with this option, the state of the logical link is 
returned in a logical link information data structure, linkinfo_dn. (See Appendix 
B on how linkinfo_dn is formatted.) 

Input Arguments 

5 specifies the number for a socket returned by the socket or the accept 

call. 

level specifies the level at which options are manipulated. The level is 

either SOL_SOCKET or DNPROTO_NSP. (See Appendix A for 
details.) 

optname specifies options to be interpreted at the level specified. For example, 
SO LINGER at the SOL_SOCKET level. 

optval, optlen specify access option values used with the setsockopt and the 
getsockopt calls. The interpretation of each argument is function 
dependent as shown here: 

setsockopt call 

optval specifies the address for a buffer which contains information for set- 

ting option values. 

optlen specifies the size of the option value buffer. 

getsockopt call 

optval specifies the address of a buffer which will contain the returned value 

for the requested option(s). 

optlen is a value result parameter. It specifies the address of an int. The value 

of optlen should initially contain the size of the buffer pointed to by 
optval. On return, it will contain the actual size of the returned value. 
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Output Arguments (for getsockopt only) 

optval specifies the buffer which contains the returned value for the 

requested socket option(s). 

optlen specifies the actual size of the returned value. 

Return Values 

If the call completes successfully, a value of is returned. An unsuccessful call returns a 
value of -1. When an error condition exists, the external variable errno will contain 
error details. See the DIAGNOSTICS section for a full description of the error messages. 

DIAGNOSTICS 



[EACCES] 
[EBADF] 

[ECONNABORTED] 
[EDOM] 

[ENETUNREACH] 
[ENOBUFS] 
[ENOPROTOOPT] 
[EOPNOTSUPP] 



Unable to disconnect the socket. 

The argument 5 does not contain a valid socket number. 

The accept connect did not complete. The peer task discon- 
nected and the connection was aborted. 

The acceptance mode is not valid. 

The network is unreachable. The network process is not 
installed. 

There are no available buffers for optional access control 
and/or user data. 

No access control information was supplied with the connec- 
tion request. 

The option is unknown. 
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4.4.13 shutdown 
NAME 

shutdown - shutdown all or part of a full duplex logical link. 
SYNTAX 

int shutdowns, how) 
int s, how; 

DESCRIPTION 

The shutdown call causes all or part of a full duplex connection on the original socket 
to be shut down. 

Input Arguments 

s specifies the number for a socket returned by the socket or the accept call . 

how specifies the type of shutdown. The how argument can be set to: 

which disallows further receives or reads. 

1 which disallows further sends or writes. 

2 which disallows further sends (or writes) and receives (or reads). 
Return Value 

If the shutdown call completes successfully, a value of is returned. If an error occurs, 
a value of -1 is returned. Additional error detail will be contained in the external vari- 
able errno. See the DIAGNOSTICS section for a full description of the error messages. 

DIAGNOSTICS 

[EBADF] The argument 5 does not contain a valid socket number. 

[ENETUNREACH] The network is unreachable. The network process is not 

installed. 

[ENOTCONN] The specified socket is not connected. 



C Language 



4-33 



4.4.14 sioctl 
NAME 

sioctl - control the operations of sockets. 
SYNTAX 

#include < sioctl. h> 

int sioctl(s, request, argp) 

int s, request; 

char *argp; (or int *argp) 

DESCRIPTION 

The sioctl call controls the operations of sockets. The call indicates whether an argu- 
ment is an input or output argument and the size of the specific argument in bytes. 

NOTE 

The DECnet-DOS function call sioctl is not compatible with DECnet- 
ULTRIX systems. See Appendix G for information on how to transport 
DECnet-DOS programs that use sioctl. 

Input Arguments 

5 specifies the number for a socket returned by the socket or the accept call . 

request specifies the I/O control function to be used. The control levels are: 

FIONREAD returns the total byte count of all messages waiting to be read. 
argp points to an int. 

FIONBIO sets/clears blocking or nonblocking I/O operation, argp points 
to a byte that contains a value of or 1. For blocking I/O, argp should 
point to a value 0. For nonblocking I/O, argp should point to a value of 1 . 

FIORENUM renumbers an assigned socket number to another number. In 
this way, the original socket number is made available again. The valid 
range for socket numbers is to 3 1 . argp points to an int. 

NOTE 

The select function call does not accept socket numbers 
that exceed this range. (See Section 4.4.10 for details.) If 
you specify a number that is already in use, an error mes- 
sage, EEXIST, is returned. 

argp specifies the address of the argument list. 

Output Argument 

argp specifies the results of the socket operations . 
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Return Value 

If the call completes successfully, a value of is returned with the following additional 
message: 

for FIONREAD, argp returns the total byte count of all messages waiting to be read. 

If an error occurs, a value of -1 is returned. Additional error detail will be contained in 
the external variable errno. See the DIAGNOSTICS section for a full description of the 
error messages. 



DIAGNOSTICS 



[EBADF] 
[EEXIST] 

[ENETUNREACH] 



The argument s does not contain a valid socket number. 
The socket number is already in use. 

The network is unreachable. The network process is not 
installed. 



[EOPNOTSUPP] 



The socket type does not support the socket I/O operation. 
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4.4.15 socket 



NAME 

socket - create an endpoint for communication and return a socket number. 
SYNTAX 

#include < types. h> 
#include <socket.h> 
#include <dn.h> 

int socket(domain, type, protocol) 
int domain, type, protocol; 

DESCRIPTION 

The socket call creates a socket and returns a socket number. A socket is an addressable 
endpoint of communications within a task. It can be used to transfer data to/from a simi- 
lar socket in another task. Subsequent function calls on this socket will reference the 
associated socket number. 

Input Arguments 

domain specifies the communications environment as AF DECnet. 

type specifies the type of communication for the socket. For example, 

SOCK__STREAM. (See Appendix A for a list of defined socket types.) 

SOCK STREAM causes bytes to accumulate until internal DECnet 

buffers are full. The receiving task does not know how many bytes 
were sent in each write operation. 

NOTE 

To prevent a program from hanging on a stream 
socket, issue the sioctl call, with the FIONREAD func- 
tion argument (See Section 4.4.14), and then read 
only those number of bytes returned by the call. You 
should also perform socket operations in 
nonblocking I/O mode. 

SOCK SEQPACKET causes bytes to be sent immediately. The receiv- 
ing task receives those bytes in one ' 'record' ' . 

protocol specifies a particular DECnet protocol to be used with the socket. (See 

Appendix A for a list of supported DECnet layers.) 

Return Value 

If the call completes successfully, the socket number is returned. This number is used 
by subsequent system calls on this socket. If an error occurs, a value of -1 is returned. 
Additional error detail will be contained in the external variable errno. See the DIAG- 
NOSTICS section for a full description of the error messages. 
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DIAGNOSTICS 

[EAFNOSUPPORT] 

[EMFILE] 
[ENETUNREACH] 

[ENOBUFS] 

[EPROTONOSUPPORT] 
[ESOCKTNOSUPPORT] 



The specified domain is not supported in this version 
of the system. 

Too many open sockets. 

The network is unreachable. The network process is 
not installed. 

No buffer space is available. The socket cannot be cre- 
ated. 

The specified protocol is not supported. 

The specified socket type is not supported in this 
address family. 
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4.4.16 sread 
NAME 

sread - read data from a socket. 
DESCRIPTION 

The sread call is used to read data from your peer. If no messages are available at the 
socket, the sread call waits for a message to arrive unless the socket is nonblocking. In 
this case, a status of -1 is returned with the external variable errno set to 
EWOULDBLOCK. 

If the socket becomes disconnected, queued data can still be received from the broken 
logical link. However, if you shutdown the socket or detach it, queued data cannot be 
received. When the logical link is not in a connected state, and all data has been read, 
the sread call returns zero bytes. 

The select call can be used to determine if more data has arrived. (See Section 4.4.10.) 

NOTE 

The DECnet-DOS function call sread is not compatible with DECnet- 
ULTRIX systems. See Appendix G for information on how to transport 
DECnet-DOS programs that use sread. 

The sread call performs the same function as the recv call (See Section 
4.4 .8) with one exception - you cannot set any flags. 

SYNTAX 

int sread(s, buffer, buflen) 
int s, buflen; 
char * buffer; 

Input Arguments 

5 specifies the number for a socket returned by the socket or the accept call. 

buffer specifies the address of the buffer which will contain the received mes- 

sage. 

buflen specifies the size of the message buffer. 

Output Argument 

buffer specifies the buffer which contains the received message. 

Return Value 

If the call succeeds, the number of read characters are returned. 

If the call returns a zero, you have either received a zero length message or the logical 
link has been disconnected. To determine the state of the logical link, use the 
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getsockopt function call with the DSO LINKINFO option (See Section 4.4. 12), or the 

DECnet utility function, dnet eo/(See Chapter 5). If the link has been disconnected, 

then all subsequent receives will return zero bytes. 

If an error occurs, a value of -1 is returned. Additional error detail will be specified in 
the external variable errno. See the DIAGNOSTICS section for a full description of the 
error messages. 

DIAGNOSTICS 

When reading normal data, the following set of error messages can occur: 
Blocking I/O 

Message Description 

[EBADF] The argument 5 does not contain a valid socket number. 

[ENETUNREACH] The network is unreachable. The network process is not 



installed. 



Nonblocking I/O 
Message 

[EBADF] 

[ENETUNREACH] 



Description 

The argument 5 does not contain a valid socket number. 

The network is unreachable. The network process is not 
installed. 

The receive operation would block because there is currently 
no data to receive. 



[EWOULDBLOCK] 
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4.4.17 swrite 
NAME 

swrite - write data to a socket. 
SYNTAX 

int swrite(s, buffer, buflen) 
int s, buflen; 
char * buffer; 

DESCRIPTION 

The swrite call is used to write data to your peer. 

If no message space is available at the socket to hold the message to be transmitted, then 
the swrite call will normally block. If the socket has been placed in nonblocking I/O 
mode, the message will not be sent, and the function will complete with the error 
EWOULDBLOCK. 

The select call can be used to determine if more data may be sent over the socket. (See 
Section 4.4. 10) 

NOTE 

The DECnet-DOS function call swrite is not compatible with DECnet- 
ULTRIX systems. See Appendix G for information on how to transport 
DECnet-DOS programs that use swrite. 

Input Arguments 

5 specifies the number for a socket returned by the socket or the accept 

call. 

buffer specifies the address of the buffer which contains the outgoing mes- 

sage. 

buflen specifies the size of the message. 

Return Value 

If the call succeeds, the number of sent characters are returned. If an error occurs, a 
value of -1 is returned. Additional error detail will be specified in the external variable 
errno. See the DIAGNOSTICS section for a full description of the error messages. 
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DIAGNOSTICS 

When sending normal data, the following set of error messages can occur 
Blocking I/O 
Message 

[EBADF] 
[EMSGSI2E] 
[ENETUNREACH] 



[ENOTCONN] 
[EPIPE] 

Nonblocking I/O 
Message 

[EBADF] 

[EMSGSIZE] 

[ENETUNREACH] 

[ENOTCONN] 

[EPIPE] 

[EWOULDBLOCK] 



Description 

The argument 5 does not contain a valid socket number. 
The size of the outgoing message is more than 2048 bytes. 



The network is unreachable. The network process is not 
installed. 

The swrite call did not complete and the link was discon- 
nected. 

The link has been disconnected, aborted or shutdown. No 
further messages can be sent. 



Description 

The argument 5 does not contain a valid socket number. 

The size of the outgoing message is more than 2048 bytes. 

The network is unreachable. The network process is not 
installed. 

The swrite call did not complete and the link was discon- 
nected. 

The link has been disconnected, aborted or shutdown. No 
further messages can be sent. 

The outbound quota was full, and the message could not be 
sent. 
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DECnet Utility Functions 



DECnet-DOS includes C language source files which are used to create a linkable 
library for DECnet-DOS applications. This library provides compatibility with the net- 
work socket interface supported by DECnet-ULTRIX. 

The DECnet utility functions are contained in the C language source files. Some of 
these routines are used for accessing the network node database and manipulating the 
data. 

Some of the DECnet utility functions include the DECnet header file <dnetdb.h>. 
This file provides DECnet definitions used with standard C functions. 

5.1 Creating the DECnet-DOS Programming Interface Library 

The file DNETLIB.SRC contains three types of files: the .C files (C language sources), 
the .H files (header files that contain definitions for the network interface) and the 
.ASM files (assembly language sources). You should refer to the appropriate installation 
guide for a complete list of these files. 

In order to interface to the DECnet-DOS network process, you should create a library 
against which to link your DECnet-DOS program(s). 

Use the following procedure to create a DECnet-DOS programming interface library: 

1. The Break Source utility, BREAKSRC, allows you to break the source file, 
DNETLIB.SRC, into separate source files for compilation and assemblies. 
BREAKSRC is supplied with the DECnet-DOS distribution kit. When you run the 
DECnet-DOS Installation Procedure (DIP), you can select to have the 
DNETLIB.SRC file split into separate files. The BREAKSRC utility will then be run 
automatically for you. For instructions on how to run DIP, refer to the appropriate 
installation guide. 
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To run BREAKSRC, use the following format: 

BREAKSRC < input file spec > < output device: \path > 

For example: 

BREAKSRC A.DNETLIB.SRC C:\DECNET\SRC\ 

2 . Use your C language compiler to compile each C language source module. Use your 
assembler to assemble each assembly source module. 

3 . After you produce an object module for each source module, build a library against 
which to link your DECnet-DOS applications programs. 

5.1.1 DECnet-DOS Programming Considerations 

The following programming considerations should be noted when writing and devel- 
oping your DECnet-DOS applications: 

1. Using the External Variable errno - Most DECnet-DOS programming interface 
functions use the external variable errno as a place to return error detail. It is 
assumed that errno has been defined externally to the programming interface as an 
int. It may already be defined in your C language run-time library, if not, your 
applications program should define it. 

2. Checking Software Compatibility - When creating DECnet-DOS applications, 
make sure that you resolve any C language compiler incompatibilities before com- 
piling the C language source modules such as long variable names or certain type 
definitions. 

3. Using Assembly Source Modules - There are assembly source modules included in 
DNETLIB.SRC. Before you can successfully call these functions from sources com- 
piled by your C language compiler, you should fulfill any assembly-format require- 
ments such as segment names. (Refer to the header file, begin. h, on the distribution 
kit as an example of specific C language compiler segment naming requirements.) 

4. Using Specific Macros - There are references to the macros/functions such as 
toupper and islower in some of the C language source modules. It is assumed that 
your C language compiler has provided a standard macro/function for them. If not, 
you can simply provide your own macros/functions. 

5 . If you are not using a C compiler that supports the signal handling function (for 
example, (ctrl/c ) trapping), then you will need to either provide your own signal 

function or comment out from the code in dnet conn any references to the 

signal( ) function and the reference to the include file, < signal. h > . 

The (ctrl/c 1 trapping, provided in dnet conn, allows you to abort a utility which 

appears to be waiting indefinitely for connections to complete. (This applies only 

to utilities that use dnet conn for making connections.) The connect function in 

dnet conn is invoked in a nonblocking socket mode. 
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If CTRL/C trapping code is commented out from dnet conn, there is the potential 

problem of leaving hung sockets and running out of system resources, should users 
decide to ictrl/c ) in the middle of nonblocking connection request attempts. 



6. If you are using a compiler that does not define the following variables: int day- 
light, long timezone and char *tzname[2], either comment these external declara- 
tions out of the header file < time.h > or define them in your C program code. 

7. The DECnet-DOS programming interface library was based on a 2-segment model. 

8. Using specific DECnet function calls - If you develop code that uses dnet getacc, 

dnet installed and dnet_path function calls, you will be unable to transport that 

code to a DECnet-ULTRLX system. These function calls are not valid on DECnet- 
ULTRIX systems. 

Caution 

If a program terminates with any active logical links (sockets), the links 
remain active. In this way, another program can start and use the same 
links. 

If the logical links are not needed, you must issue an sclose function 
call before a program is terminated with an EXIT, (ctrl/z ) or ictrl/c ) . If 
too many links are left active, an error message, indicating that no 
more buffers are available or insufficient network resources, is 
reported. This causes the network to become unusable. To completely 
deactivate any logical links, run the Network Control Program (NCP) 
and issue the SET KNOWN LINKS command with STATE OFF. (See the 
DECnet-DOS User's Guide for more information on this command.) 
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5.2 DECnet Utility Function Calls 

The following sections describe the DECnet utility function calls for C programs. The 
calls are summarized in the table below: 

Table 5-1 : DECnet Utility Function Calls 



DECnet Call Description 

bcmp C ompare byte strings . 

bcopy Copy n bytes from one specific string to another string, 

bzero Zero n bytes in a specific string. 

dnet addr Convert an ASCII node address string to binary and return a pointer to a 

dn naddr data structure. 

dnet conn Connect to the specified target network object on a remote node and send 

along access control information and/or optional data. 

dnet eof Test the current state of the connection. 

dnet getacc Search the incoming access database file, DECACC.DAT, for access control 

information that is associated with a given user name. The access control 
information set by the NCP command SET ACCESS is stored in the database 
file, DECACC.DAT. 

dnet getalias Return default access control information by node name. 

dnet htoa Search the node database. If the node name is found, a pointer to the DEC- 

net ASCII node name string is returned. Otherwise, a pointer to the DEC- 
net ASCII node address string is returned. If the function fails to return a 
valid node name or address string, a pointer to the string "Punknown?" is 
returned. 

dnet installed Perform an installation check on the specific software module. 

dnet ntoa Specify a pointer to the dn naddr data structure which contains the 

binary node address. If the function completes successfully, a pointer to 
the ASCII string representation of the DECnet node address is returned. 

dnet path Return a modified file name which contains the DECnet database device 

and path name prefixed to the file name. 

getnodeadd Return the address of your local DECnet-DOS node. 

getnodeent Access the network node database and return complete node information 

given only a node address or node name. 

getnodename Return the ASCII string representation of your local DECnet-DOS node. 

nerror Produce DECnet error messages and output the ASCII text string to stdout. 

perror Produce an ULTRIX error message appropriate to the last detected system 

error, and output the ASCII text string to stdout. 
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5.2.1 bcmp 
NAME 

bcmp - compare byte strings. 
SYNTAX 

int bcmp(s1 , s2, n) 

char *s1, *s2; 
int n; 

DESCRIPTION 

bcmp compares byte strings to see if they are matching character strings. It is assumed 
that the strings are of equal length. 

Input Arguments 

si specifies the address of the first character string. 

s2 specifies the address of the second character string. 

n is the length of the strings. 

Return Value 

If a match is found, the value of is returned. Otherwise, a nonzero value is returned. 
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5.2.2 bcopy 
NAME 

bcopy - copy n bytes from one specific string to another string. 
SYNTAX 

int bcopy(s1, s2, n) 

char *s1,*s2; 
int n;* 

DESCRIPTION 

bcopy copies n bytes from one specific string to another string. 
Input Arguments 

si is the character pointer to the source string. 

s2 is the character pointer to the destination string. 

n specifies the number of bytes to be copied. 

Return Value 

The number of bytes copied from the source string to the destination string is returned. 
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5.2.3 bzero 
NAME 

bzero - zeroes n bytes in a specified string. 
SYNTAX 

int bzero(s1 , n) 

char *s1; 
int n;* 

DESCRIPTION 

bzero zeroes n bytes in a specified string. 
Input Arguments 

*sl is the character pointer to the specified string. 

n specifies the number of bytes to be zeroed. 

Return Value 

The number of bytes zeroed in the specified string is returned. 
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5.2.4 dnet addr 

NAME 

dnet addr - convert an ASCII node address string to binary and return a pointer to a 

dn naddr data structure. 

SYNTAX 

struct dn naddr *dnet addr(cp) 

char *cp; 
DESCRIPTION 

In area based networks, a DECnet node address includes an area number and a node 

number, dnet addr converts an ASCII node address string to binary and returns a 

pointer to a dn naddr data structure. This information is required for the 

sockaddr_dn data structure. (See Appendix B on how these data structures are format- 
ted.) 

Input Argument 

cp is the character pointer to the ASCII node address string. The DECnet node 

address is specified as a. n 

where 

a is the area number 
n is the node number 
Return Argument 

dn_naddr specifies the node address data structure. A user retrieves data from 
the fields filled in by this function call. The fields are: 

a len specifies the length of the returned node address. 

a add specifies the node address. 

If the call succeeds, a pointer to a dn naddr data structure is returned. Otherwise, a 

null value is returned. 

NOTE 

If you plan to call this function again before you are finished using the 
data, you must copy the data into a local buffer. 
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5.2.5 dnet conn 

NAME 

dnet conn - connect to the specified target network object on a remote node and 

send along access control and/or optional user data. 

SYNTAX 



int dnet conn(node, object, sock type, out data, out len, 

in data, in len) 

char *node; 

char 'object; 

int sock type; 

u char *out data, *in data, 

int out len, *in len; 



DESCRIPTION 

dnet conn establishes a connection to the specified target DECnet object on a remote 

node. If no access control information is supplied as part of the node input argument, 
the default access control information (if found in the access control database) will be 
sent. Optional data can also be passed with the function. 

dnet conn supports password prompting based on the input node specification 

string. You are asked to supply a password whenever: 

• the password field in the node specification is either a question mark (?) or an aster- 
isk (*). 

• the user field is present but the password field is missing. 

The following example node specifications will cause prompting for passwords: 

dnet_conn ( "boston/ reve re" , . . . ) 
dnet_conn ( "boston/ reve re/? " , . . .) 
dnet__conn("boston/revere/*" , . . .) 

dnet conn supports outgoing proxy login access. Outgoing proxy allows the local 

node to initiate proxy login access to the remote node, but does not allow proxy login 
access from the remote node to the local node. Before you are permitted to use proxy 
login, the following must take place: 

• proxy login access must be supported at the remote node. 

• the Executor (local) node must have a user name set up in its node database. This 
user name is passed in outgoing connection requests and may be used for proxy 
login access. To set up access control information, refer to the discussion on the 
NCP utility in the DECnet-DOS User's Guide. 

If access control information is not explicitly supplied with an input node name, 
dnet conn will check the node database for implicit access control information. If 
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implicit access control does not exist, proxy login will take place with the Executor 
node's user name and passed in the outgoing connection request. 

The following examples show the use of proxy login access with the dnet conn func- 
tion call: 

The Executor (local) node has set up TASHA as the user name in the local node's data- 
base. The remote node BOSTON is stored as an entry in the local node's database with- 
out any access control information. 

1 . no proxy, null access control information is explicitly specified: 
dnet conn ( " BOSTON// " , . . . ) 

2 . proxy will be passed, no explicit access control information, no implicit access con- 
trol information for node BOSTON in the database: 

dnet conn ( " BOSTON " , . . .) 

The Executor (local) node has set up TASHA as the user name. The remote node BOS- 
TON is stored as an entry in the local node's database with TASHA as the user name/ 
access control information. 

1 . no proxy, null access control information is explicitly specified: 
dnet_conn ( " BOSTON// ",...) 

2 . no proxy, the implicit access control information for node BOSTON will be used: 
dnet_conn ( " BOSTON ",...) 

A target task can return a 1- to 16-byte optional data message when it accepts or rejects 
the connection request. 

When a program which uses dnet conn fails to complete a connection request, nerror 

can subsequently be called in order to display the DECnet error message. 

Input Arguments 

node specifies the address of the string which contains the remote node 

name or address and any access control information. Node names are 
always converted to uppercase before being processed by this func- 
tion. Access control information is passed as supplied with regard to 
case. 

To pass access control information, the node string can take one of 
the following formats: 

' i node_name I user I password! account' ' 

or 

' 'area. node_number/ user/password/ account' ' 
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object 



sock_type 



out data 



out ten 



in_data 



in len 



Return Value 



To pass null access control information, the node string can take one 
of the following formats: 

"node_nameir ' 

or 

' 'area. node_numberl 7' ' 

specifies the address of the string which contains the specified target 
DECnet object. The object string can be specified in one of the follow- 
ing ways: 

1 . To access a target object by supplying an object. You should note 
that the object name is passed as supplied, with regard to case. 

' ' target object name 1 ' 

2 . To access a target object by object number. 

' ' #target object number 1 ' 

is when creating a sequenced socket packet, and 1 when creating a 
stream socket. 

specifies the address of the outgoing optional user data buffer. If not 
required, supply a null pointer. 

specifies the size of the optional outgoing message. The message 
length can be up to 16 bytes. If not required, supply a null value. 

specifies the address of the buffer which will store the optional incom- 
ing message. If not required, supply a null pointer. 

specifies the address of the location in which the value will be stored. 
It should initially contain the size of the buffer pointed to by 
in_data. On return, it will contain the actual size of the optional 
incoming message. If not required, supply a null pointer. 



If the function completes successfully, the socket number is returned. If an error 
occurs, a value of -1 is returned. Additional error detail will be contained in the exter- 
nal variable errno. See the DIAGNOSTICS section for a full description of the error mes- 
sages. 



DIAGNOSTICS 

[E2BIG] 
[EACCES] 

[EADDRNOTAVAIL] 



An argument is too long. 

Access control information was rejected. 

The node name is undefined. 
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[ED EST ADDRREQ] 

[ENAMETOOLONG] 

[ENETUNREACH] 

[ESRCH] 



A specific destination address is required. 
The node name is invalid. 

The network is unreachable. The network process is not 
installed. 

The object is unknown. 

NOTE 



Additional errors may be returned by the socket, setsockopt, and the 
connect function calls which are called from within dnet conn. 
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5.2.6 dnet eof 

NAME 

dnet eof - test the current state of the connection. 

SYNTAX 

int dnet eof(sock) 

int sock; 
DESCRIPTION 

dnet eof tests the current state of the connection. 

Input Argument 

sock specifies the socket whose connection is to be checked. 

Return Value 

If the connection is determined to be active (either a running or a connecting state), a 
value of is returned. If the connection is inactive, a value of 1 is returned. 

NOTE 

If a bad socket number is supplied with dnet eof, a value of 1 is 

returned. However, this value is not a true indication of an invalid 
socket number. 
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5.2.7 dnet getacc 

NAME 

dnet getacc - searches the incoming access database for access control information 

that is associated with a given user name. 

SYNTAX 

struct dnet accent *dnet getacc(nacc) 

struct dnet accent *nacc; 

DESCRIPTION 

dnet__getacc searches the incoming access database file, DECACC.DAT, for access con- 
trol information that is associated with a given user name. The access control informa- 
tion set by the NCP command SET ACCESS is stored in the database file, DECACC.DAT. 

NOTE 

If you develop code that uses dnet__getacc, you will be unable to trans- 
port that code to a DECnet-ULTRIX system. This call is not valid on 
DECnet-ULTRIX systems. 

Input Argument 

nacc is a character pointer to an access control information block contain- 

ing the user name to be matched. The string consists of 1 to 39 alpha- 
betic characters. This string must be identical to the user string set up 
by the NCP command SET ACCESS. (Use the NCP command SHOW 
KNOWN ACCESS to display the string.) Refer to the DECnet-DOS 
User's Guide on using these commands. 

Return Argument 

nacc specifies the access control information block data structure 

dnet accent. A user retrieves information filled in by this function 

call. (See Appendix B on how dnet accent is formatted.) 

The following data fields can be filled in by this function call: 
acc status is used internally by this function call. 

acc type specifies the type of privilege associated with a user name. 

The four access types are: for no access rights, 1 - read only 
access, 2 - write only access and 3 for read and write access. 

acc user specifies the user name. It consists of a 1 to 39 alphabetic 

character string terminated by a null character. 

acc pass specifies the password associated with a user name. It con- 

sists of a 1 to 39 alphabetic character string terminated by a 
null character. 
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If there is a match, a character pointer to the access control information block associ- 
ated with the user string is returned. The access type is always returned along with any 
user and password information. 

A value of is returned if there is no match, or the DECnet database path cannot be 
found for DECACC.DAT using the function dnet_path. (See Section 5 2.12.) 

NOTE 

If you plan to use this function again before you are finished using the 
data, you must copy the data into a local structure. 
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5.2.8 dnet_getalias 
NAME 

dnet getalias - returns default access control information by node name. 

SYNTAX 

char *dnet getalias(node) 

char *node; 
DESCRIPTION 

dnet__getalias retrieves any default access control information associated with a spe- 
cific node. 

Input Argument 

node is a character pointer to a node name. The node name is forced to 

uppercase and then processed by the function. 

Return Argument 

If the node has default access control information associated with it, the node name fol- 
lowed by the access data is retrieved. The extended node name string is returned as 
node_name/user I password! account. This data was set up in the permanent data- 
bases, DECNODE.DAT and DEC ALIAS . DAT , using the Network Control Program 
(NCP). 

If no access control data can be found, a null pointer is returned. 

NOTE 

If you plan to call this function again before you are finished using the 
data, you must copy the data into a local buffer. 
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5.2.9 dnet htoa 

NAME 

dnet htoa - search the node database. If the node name is found, a pointer to the DEC- 

net ASCII node name string is returned. Otherwise, a pointer to the DECnet ASCII node 
address string is returned. If the function fails, a pointer to the string "Punknown?" is 
returned. 

SYNTAX 

char *dnet htoa(add) 

struct dn naddr *add; 

DESCRIPTION 

dnet htoa searches the node database. If the node name is found, a pointer to the DEC- 
net ASCII node name string is returned. If the node name is not found, a pointer to the 
DECnet ASCII node address string is returned. 

Input Argument 

add specifies a pointer to a structure of the type, dn naddr, which con- 
tains the node address. The format is area.number. (Refer to Appendix 
B on how the dn naddr data structure is formatted.) 

Return Value 

If the node name is found, a pointer to the DECnet ASCII node name string is returned. 
Otherwise, a pointer to the DECnet ASCII node address string is returned. 

If the function call fails to return a valid node name or address string, a pointer to the 
string "?unknown?" is returned. 

NOTE 

If you plan to call this function again before you are finished using the 
data, you must copy the data into a local structure. 
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5.2.10 dnet installed 



NAME 

dnet installed - perform an installation check on a specific software module. 

SYNTAX 

int dnet installed(vector, tla) 

short vector; 
char *tla; 

DESCRIPTION 

dnet installed performs an installation check on a specific software module. You sup- 
ply the interrupt vector number and the 3 -letter acronym for the software module. 

If the software module is installed, the 2-byte software version number is returned. The 
low byte is the major version number. The high byte is the minor version number. Oth- 
erwise, a value of -1 is returned. 

NOTE 

If you develop code that uses dnet installed, you will be unable to 

transport that code to a DECnet-ULTRIX system. This function call is 
not valid on DECnet-ULTRIX systems. 

Input Arguments 

vector specifies the interrupt vector number for the software module . Appen- 

dix A lists the interrupt vector numbers for the defined software mod- 
ules. 

tla is the 3-letter acronym for the software module. The acronym is 

passed as supplied, with regard to case. For example, DNP is the acro- 
nym for the DECnet Network Process. It must be passed as uppercase. 
See Appendix A for a list of defined software modules . 

Return Value 

If the installation check successfully completes, the 2-byte software version number is 
returned. Otherwise, a value of -1 is returned. 
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5.2.11 dnet ntoa 

NAME 

dnet ntoa - Convert a DECnet node address from binary form to ASCII form. 

SYNTAX 

char *dnet ntoa(add) 

struct dn naddr *add; 

DESCRIPTION 

dnet ntoa converts a DECnet node address from binary form to ASCII form. 

Input Argument 

add specifies a pointer to a structure of the type, dn naddr, which con- 
tains the binary node address. (See Appendix B on how the dn naddr 

data structure is formatted.) 

Return Value 

If the function completes successfully, a pointer to the ASCII string representation of 
the DECnet node address is returned. The format is area. number. 

If the function call fails to return a valid node name or address string, a pointer to the 
string "Punknown?" is returned. 

NOTE 

If you plan to call this function again before you are finished using the 
data, you must copy the data into a local structure. 
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5.2.12 dnet_path 
NAME 

dnet path - return a modified file name that contains the DECnet database device and 

path name prefixed to the specified input file name. 

SYNTAX 

char *dnet path(file name) 

char *file name; 

DESCRIPTION 

Given a character string pointer to a file name, dnet_path returns a modified file name 
that contains the DECnet database device and path name prefixed to the specified input 
file. It is recommended that all user-created DECnet-DOS database files be located in 
the same DECnet directory. 

For example: 

Call: 

new_f i I e_name = dnet_path("NCPHELP.BIN"); 
Returns: 

new_f i I e_name = "c:\decnet\NCPHELP.BIN" 

The DECnet database device and path name should be specified as input arguments to 
the DLL and/or DNP command lines in your AUTOEXEC.BAT file. To do this, edit your 
AUTOEXEC.BAT file using EDLIN or a similar text editor. 

IMPORTANT 

The dnet_path function call differs from Version 1 .0. You can no lon- 
ger set the DECnet database device and path names using the NCP com- 
mand SET EXECUTOR. However, you can still display the database 
path specification. To do this, issue the NCP command SHOW EXECU- 
TOR CHARACTERISTICS. For information on using this command, 
refer to the DECnet-DOS User's Guide. 

If you develop code that uses dnet__path, you will be unable to trans- 
port that code to a DECnet-ULTRIX system. This function call is not 
valid on DECnet-ULTRIX systems. 

When the system is rebooted, DNP and/or DLL will use its command line argument or 
default to the current device Adecnet as the path specification. 

To change the DECnet database path, you will need to specify a new path specification 
as command line input the next time that DLL and/or DNP are installed. 
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DECnet-DOS Version 1.1 supports Ethernet and asynchronous DDCMP configura- 
tions. DECnet-Rainbow VI. 1 only supports asynchronous DDCMP configurations. 
The following examples illustrate acceptable ways for specifying the DECnet database 
path. 

If you have an Ethernet setup. 

Example 1: The Scheduler (SCH), Data Link Layer (DLL) and DECnet Network Pro- 
cess (DNP) files are to be installed. The DLL and DNP command lines include a defined 
DECnet database path. The DLL path is used. 



SCH 

DLL c:\decnet\vll 
DNP c:\decnet\vll 

Example 2: SCH, DLL and DNP files are to be installed. Only the DLL command line 
includes a defined DECnet database path. A database path is not defined for DNP. The 
database path set for DLL will also be used by DNP. 



SCH 

DLL c:\decnet\vll 
DNP 

Example 3: SCH, DLL and DNP files are to be installed. The DLL and DNP command 
lines do not include defined database paths. For this setup, the default DECnet database 
path (current device Adecnet) set for DLL will also be used by DNP. 



SCH 
DLL 
DNP 

If you have an asynchronous DDCMP setup. 

Example 1: SCH and DNP files are to be installed. The DNP command line includes a 
defined DECnet database path. The DLL file is not required for asynchronous opera- 
tions. 



SCH 

DNP c:\decnet\vll 
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Example 2 : SCH, and DNP files are to be installed. A DECnet database path is not speci- 
fied for DNP. Therefore, the default database path (current drive Adecnet) will be used 
by DNP. 

SCH 
DNP 

Return Value 

If the call completes successfully, a pointer to a modified file name that contains the 
DECnet database device and path name prefixed to the file is returned. 
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5.2.13 getnodeadd 
NAME 

getnodeadd - return the address of your local DECnet-DOS node. 
SYNTAX 

struct dn naddr *getnodeadd(); 

DESCRIPTION 

getnodeadd returns a pointer to a dn naddr data structure which contains the DEC- 

net node address of the local DECnet-DOS node. 

Return Argument 

dn naddr specifies the node address data structure. A user retrieves data from 

the fields filled in by this function call. The fields are: 

a len specifies the length of the returned DECnet-DOS node 

address. 

a add specifies the DECnet-DOS node address. 

If the call succeeds, a pointer to a dn naddr data structure is returned. If an error 

occurs, a null value is returned. 

NOTE 

The dn naddr data structure will be reused by additional calls. To 

keep this information, you must copy the data into a local structure. 
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5.2.14 getnodeent 
NAME 

getnodeent, getnodebyaddr, getnodebyname, setnodeent, endnodeent - access the net- 
work node database and return complete node information given only a node address 
or node name. 

SYNTAX 

#include <dnetdb.h> 



struct nodeent *getnodeent() 

struct nodeent *getnodebyname(name) 

char *name; 

struct nodeent *getnodebyaddr(addr, len, type) 

char *addr; 

int len, type; 

setnodeent(stayopen) 

int stay open; 



endnodeent()* 
DESCRIPTION 

These functions access the network node database and return complete node informa- 
tion given only a node address or node name. Each getnodeent, getnodebyname and 
getnodebyaddr function returns a pointer to a single static nodeent structure. This 
structure contains the broken out fields of an entry in the network node database. 

getnodeent returns a pointer to the next entry of the database. 

setnodeent positions you at the beginning of the database. If the stayopen flag is set to 
nonzero, the node database is not closed after each call to getnodeent (either directly, 
or indirectly through one of the other "getnode" calls). 

endnodeent closes the database file. 

getnodebyname and getnodebyaddr sequentially search from the beginning of the data- 
base until a matching node name or node address is found, or until an end of the data- 
base is encountered. Node names are stored in the network node database as upper- 
case. Therefore, comparisons of node name strings to node names stored in the 
database are forced to be uppercase. Node addresses are always arranged in ascending 
numeric order. 
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Input Arguments 

name specifies the address of the buffer containing the DECnet node name 

string. 

addr specifies the address of the buffer containing the DECnet node 

address string. 

len is the length of the node's address string in bytes. 
type is the address type AF DECnet. 

stay open specifies a call dependent argument. If set to nonzero, the network 

node database is kept open for subsequent "getnode" calls. 

Return Value 

If the function, other than setnodeent and endnodeent, complete successfully, the 
address for the nodeent structure is returned. 

nodeent specifies the node address database structure. A user retrieves data 

from the fields filled in by this function call. The following data fields 
can be modified: 

*n name points to a string which is the name of the DECnet node. 

n addrtype specifies the address type AF DECnet. 

n addr specifies the DECnet network address for the node. 

If an error or an EOF occurs, a null pointer is returned. 

If setnodeent completes successfully, a value of is returned. Otherwise, a value of -1 
is returned. 

NOTE 

The nodeent structure will be reused by additional calls. To keep this 
information, you must copy the data into a local structure. 
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5.2.15 getnodename 
NAME 

getnodename - return the DECnet node name of your local DECnet-DOS node. 
SYNTAX 

char *getnodename(); 
DESCRIPTION 

getnodename returns the ASCII string representation of your local DECnet-DOS node 
name. 

Return Value 

If the function call is successful, your local DECnet node name is returned. Otherwise, 
a null pointer is returned. 
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5.2.16 nerror 
NAME 

nerror - produce DECnet system error messages. 

SYNTAX 

nerror(s) 
char *s; 

DESCRIPTION 

nerror produces DECnet error messages by mapping standard errno values to their 
equivalent DECnet error messages. First the characters pointed to by s are output to 
stdout, followed by a colon, and then the resulting DECnet error text. The error num- 
ber is taken from the external variable, errno, which is set when an error occurs. 

If a program makes a call to dnet conn which fails, nerror should be subsequently 

called in order to display the DECnet error text. 

Input Argument 

*c is the character pointer to the ASCII text string to be displayed before the 

DECnet error text is displayed. 

Output Argument 

The characters pointed to by s are output to stdout, followed by the colon, and then the 
resulting DECnet error text. You should refer to Section 5.2.5 for the list of DECnet 
error messages returned by dnet conn. 

NOTE 

This call is not ULTRIX compatible. For the ULTRIX call, the log is out- 
put to stderr. 
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5.2.17 perror 
NAME 

perror - produce a standard ULTRIX error message appropriate to the last detected sys- 
tem error. 

SYNTAX 

perror(cp) 

char *cp; 

DESCRIPTION 

perror produces a standard ULTRIX error message appropriate to the last detected sys- 
tem error. First the character string is output, followed by a colon, and then the stan- 
dard ULTRIX error message indexed by errno. 

For example, 

per ror ("Last error was ") 

Input Argument 

*cp is the character pointer to the ASCII text string to be displayed before the 

ULTRIX error text is displayed. 

NOTE 

The log from perror is output to stdout. This call is not 
ULTRIX compatible. For the ULTRIX call, the log is output 
to stderr. 
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Assembly Language 



Application programs written in assembly language can establish logical links and 
exchange data over the network. Nontransparent task-to-task communication requires 
specific network process interface calls. The implementation of these programming 
calls are discussed in this chapter. 

6.1 DECnet-DOS Network Process 

The DECnet-DOS network process is a terminate and stay resident task which is 
loaded into memory. It remains in memory once it is run. The DECnet-DOS network 
process supports blocking and nonblocking synchronous, and asynchronous I/O. 

6.2 DECnet Network Process Installation Check 

Before accessing the DECnet network process, you should check to see if the network 
process has been installed. You must first issue the MS-DOS interrupt function call 35H 
(Get Interrupt Vector) with the DNP vector number as input. This function call returns 
a pointer to the DNP interrupt entry point. 

On entry, the AH register contains the hexadecimal code, 35H. The AL register con- 
tains a hexadecimal interrupt number. For example, 6EH is the interrupt number for 
the DECnet network process. On return, the ES:BX register contains the CS:IP inter- 
rupt vector for the specified interrupt. 
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The interrupt function call 35H is described below. 



On 

Entry 


| 8086/8088 Register Contents 


AH 


| 35H (hexadecimal function code) 

1 


AL 


| 6E (interrupt vector number for 
| the DECnet network process) 




On 

Return 


| 8086/8088 Register Contents 

1 


ES:BX 


| pointer to the interrupt 
| handling routine 



Figure 6-1 : MS-DOS Interrupt Function Call 35H, Get Vector 
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Using the interrupt vector that identifies the DECnet network process (DNP) module, 
you can examine the contents of the five bytes that precede the DNP entry point. Use 
the following procedure: 

• Check the first 3 bytes for the 3 -letter acronym for the software module. In this 
case, the acronym is DNP. 

• Examine the 2-byte software version number. The low byte is the major version 
number, and the high byte is the minor version number. 

The installation check procedure is described below: 



In Memory 

+ + 

j major version ! 

+ + 

| minor version | 
+ + 

Returned by GET INTERRUPT VECTOR | D \ 

+ + 

+ + I N | 

| segment | + + 

+ + I P I 

| offset | entry + + 

+ + > DNP : | code ! 

point + + 
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6.3 Using the I/O Control Block 



All I/O to the network process is handled via DECnet-DOS network process interface 
calls. A data structure called the I/O Control Block (IOCB) transfers data to/from the net- 
work process. The address of the IOCB data structure is passed directly to the network 
process. 

To issue a network process interface call, you must first create an IOCB for that call. 
Refer to the individual call descriptions (Sections 6.7.1 to 6.7.20) on how to set up the 
IOCB. To pass information to the DECnet network process, you must issue the inter- 
rupt function call 6EH. You use this call for I/O requests to the network process: 

• set up data in an IOCB 

• move the address of the IOCB into the DS:DX register 

• move the DECnet network process code, DE, into the AH register 

• move a value of 1 into the AL register as the function code for an IOCB function 
request 

• issue the interrupt function call 6EH 

On return, status information is returned in the IOCB for the network process interface 
call addressed by this interrupt function. If the call 6EH completes successfully, the 

IOCB's data member, io status, returns a value of 0. Data may also be returned in the 

IOCB. You should refer to the individual call descriptions for details on any returned 
data. 

In all I/O modes, if the call 6EH is unsuccessful, io status returns a -1 value. In asyn- 
chronous mode, if the call does not complete, a value of -2 is returned. Another 

(C)IOCB data member, io errno returns additional error detail. See Appendix C for a 

list of error conditions. 

The function call 6EH is described below: 



On 


1 8086/8088 Register Contents 


Entry 


i 


AH 


| DE (DECnet network process 




| hexadecimal code) 


DS:DX 


| address of IOCB (or CIOCB) 


AL 


| 1 (IOCB Function request) 



Figure 6-2: Interrupt Function Call 6EH, IOCB Request 



6-4 



DECnet-DOS Programmer's Reference Manual 



6.3.1 I/O Control Block Structure 

The I/O Control Block consists of a header substructure and a parameter list. The mem- 
bers of the IOCB header are listed in the following table: 

Table 6-1 : IOCB Header Data Members 



Member 

io^fcode 

io socket 

io__flags 

io status 

io errno 

io psize 



Size 

1 byte 

2 bytes 
2 bytes 
2 bytes 
2 bytes 
2 bytes 



Data Contents 

network process call specific function code (See Section 
6.7.) 

socket number 
flag option 
returned status value 
returned error value 
parameter list size or buffer size 



The IOCB parameter list depends on the particular network process interface call. It 
may contain one of the following members: 

Table 6-2: IOCB Parameter List Members 



Member 


Size 


Data Contents 


attach__jdn 


12 bytes 


socket creation data 


io buffer 


4 bytes 


data buffer offset 


listen^jdn 


2 bytes 


maximum number of incoming connects 


localinfo^jdn 


20 bytes 


local node information 


select^jdn 


16 bytes 


socket I/O descriptors 


shutdown— dn 


2 bytes 


type of logical link shutdown 


sioctl^jin 


8 bytes 


socket I/O control 


sockaddr__dn 


26 bytes 


socket definitions 


sockopt_dn 


12 bytes 


socket options 
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The members of an IOCB data structure are illustrated below: 
Bytes Data Fields: Input or Output 



lo 
hi 
lo 
hi 
lo 
hi 
lo 
hi 
lo 
hi 



■ + < 

i Function code (io fcode) 

■ + 

| Socket (io socket) 

■ + I 

I v 



Flags ( io flags ) 

I 

V 

Status [io status) 
V 

Er rno ( io errno ) 
V 

Parameter size ( io psize) < 
V 

< 

Data structure(s) 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 



Figure 6-3: An IOCB Data Structure 
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6.4 Using the Callback I/O Control Block 



To request a callback routine when specific calls complete, you must set up a data struc- 
ture called the Callback I/O Control Block (CIOCB). The address of the CIOCB data 
structure is passed directly to the DECnet network process. To issue a DECnet-DOS 
call with a callback routine, you must first create a CIOCB for that call. Refer to individ- 
ual call descriptions on how to set up the CIOCB. To pass information to the DECnet 
network process, issue the interrupt function call 6EH: (Refer to Section 6.3 for a 
description of the function call 6EH.) 

• set up data in a CIOCB 

• move the address of the CIOCB into the DS.DX register 

• move the DECnet network process code, DE, into the AH register 

• move a value of 1 into the AL register as the function code for a CIOCB function 
request 

6.4.1 Callback I/O Control Block Structure 

The Callback I/O Control Block consists of a header substructure, a parameter list and 
the address of the callback routine. The CIOCB uses the same header substructure and 
parameter list as the IOCB. Their data members are listed in Tables 6-1 and 6-2. The 
additional data member is the address of the callback routine which requires 4 bytes. 
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Its location along with the other members of the CIOCB are illustrated below: 



Bytes 



Data Fields: Input or Output 



lo 



hi 



lo j 

+ + 

| hi j 
+ + 

! lo j 
+ + 

! hi | 

+ + 

i lo ! 

+ + 

I hi | 

+ + 

! lo ! 

+ + 

■ hi i 
+ + 



< 

Function code ( io fcode 



Socket (io socket 

j 

V 



Flags ( io flags ) 

\ 

V 

Status (io status) 
V 

Er rno ( io errno ) 
V 

Parameter size (io psize) < 
V 

< 

Data structure(s) 



CIOCB 
HEADER 



CIOCB 
PARAMETER 
LIST 



lo i 

+ + 

i hi | 
+ + 

lo ! 

+ - - + 

! hi j 
+ + 



< 

< 

offset 



segment 



io callback 



CALLBACK 
ADDRESS 



Figure 6-4: A CIOCB Data Structure 
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6.5 Blocking and Nonblocking Synchronous I/O vs. Asynchronous 
I/O 

DECnet-DOS supports three ways of handling network I/O: blocking synchronous, 
nonblocking synchronous and asynchronous I/O. Each method is independent of the 
other. 

When a DECnet-DOS call is issued in blocking synchronous mode, the software issu- 
ing the call does not regain control until the call completes or has failed. When 
nonblocking synchronous I/O is set, socket operations return to the calling program 
after the operation has been started, but not necessarily completed. Some operations 
must be restarted. If on the other hand, the operation can be performed immediately, it 
will either be completed or fail. When it fails, an error reason such as EWOULDBLOCK 
or ENOBUFS will be reported. 

When asynchronous I/O is used, control returns to the calling program immediately 
after the DECnet network process records the call request. The network process may 
complete the request immediately or wait for a later time. There are two ways for you 
to check the status of an asynchronous DECnet-DOS call: use a callback routine and/or 
poll for status. 

When using asynchronous I/O, the calling program can request that a routine be called 
upon completion. This routine is referred to as the callback routine. Callback routines 
can only be implemented with the asynchronous form of a function call. Asynchronous 
callbacks are valid for the following seven calls. It is also valid to issue these calls asyn- 
chronously without a callback as well as synchronously. The calls are: 

• ACCEPT (Section 6.7.2) 

• CONNECT (Section 6.7.6) 

• RCVD (Section 6.7. 12) 

• RC VOOB (Section 6.7.13) 

• SELECT (Section 6.7. 14) 

• SEND (Section 6.7. 15) 

• SENDOOB (Section 6.7. 16) 

NOTE 

Information pertaining to the asynchronous form of function calls is 
indicated by the caption For Asynchronous Mode. 

The function calls not appearing in this list can be issued asynchro- 
nously without a callback routine. Due to the way that the network 
process handles these calls, they will still complete immediately. 
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If your program does not implement callback routine(s), you should poll for status. To 

do this, examine the io status field in the IOCB. A value of either -2, or -1 may be 

returned. A value of -2 indicates pending or no change in status. When the call success- 
fully completes, a value of is returned in the to status field. For some calls, you will 

be able to retrieve data from a data structure which is filled in by the call. 

If the call is unsuccessful, io status returns a value of -1 . Additional error reason will 

be contained in the io errno field. The error messages are listed in the DIAGNOSTICS 

section under each call description. 

You can use callbacks and also poll for status. When you do this, the following status 
values can be returned: 

Status 

Value Meaning 

-2 No change in status. The callback routine has not been called. 

The call has completed. The callback routine was already called. 

- 1 The callback was already called, but there was an error in completing 

the call. 

6.5.1 Using a Callback Routine 

When you write a program that uses a callback routine, follow these guidelines: 

• There is a valid stack, but not the user's stack. 

• The address of the IOCB is in the DS:DX register. 

• The address of the IOCB is on the stack. 

• You preserve all registers except for the AX, BC, CX and DX registers. 

• You must be sure to do a far return. 

• When you implement callback routines, you cannot do any MS-DOS function calls 
or synchronous network I/O inside the callback routine. You can still do asynchro- 
nous network I/O. 

6.5.2 Setting the io flags Field 

You can set more than one bit in the io__flags field which is included in the I/O control 
block. Bits for asynchronous I/O and callback routines can be used in conjunction with 
other bits for "peeking" at messages, and for sending and receiving a multi-part mes- 
sage. How these bits are used with a specific function call appear in the individual call 
descriptions. Additional information about these flag options appear in Appendix A. 
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6.6 Using Socket Numbers with DECnet Network Process Interface 
Calls 



The network process uses socket numbers to identify a particular I/O session. A socket 
number must be assigned by the user before he can proceed with further network I/O. 
To assign a socket number, issue the ATTACH function call. (See Section 6.7.3 for a call 
description.) The assigned socket number is then used in the IOCB for subsequent net- 
work calls. The DETACH function call instructs DNP to deallocate any network 
resources associated with the attached socket, and make the socket and resources avail- 
able again for network I/O. 



6.7 Network Process Interface Calls 

The following sections describe the synchronous form of the network process inter- 
face calls used for assembly language programs. An IOCB is passed to the network pro- 
cess with each call. Each IOCB contains a header and a parameter list. The members of 
the IOCB header are detailed with each call. For some calls, the IOCB also includes a 
data structure or a buffer address. The type of data structure is determined by the spe- 
cific call. The members of the data structures are detailed in a similar manner. 

Information pertaining to the asynchronous form of certain function calls is indicated 
by the caption For Asynchronous Mode. Refer to Section 6.5 for a list of function calls 
that have an asynchronous and a synchronous form. 

The assembly language network process interface calls are summarized in the follow- 
ing table: 

Table 6-3: Assembly Language Network Process Interface Calls 



Decimal 
Value 

10 



Function 

ABORT 

ACCEPT 

ATTACH 
BIND 
CONNECT 
DETACH 



Description 

Disconnect all logical links (if any) and detach the 

sockets that do not have the option SO KEEP ALIVE 

set. 

Accept an incoming connection request on a socket, 
and return a socket number. 

Create a socket and attach a socket number. 

Assign an object name or number to a socket. 

Initiate a connection request on a socket. 

Disconnect all associated active logical links, and 
detach the specified socket and any associated 
sockets, only if the option SO KEEPALIVE is not set. 



(continued on next page) 



Assembly Language 



6-11 



Table 6-3 (cont.): Assembly Language Network Process Interface Calls 
Decimal 



Value Function Description 

6 DISCONNECT Disconnect from the peer socket, and terminate the 

logical link connection. 

26 GETSOCKOPT Get the options associated with sockets. 

3 LISTEN Listen for pending connections on a socket. 

22 LOCALINFO Retrieve network information for the local node. 
1 6 PEERADDR Retrieve information about your peer socket . 

8 RCVD Receive data on a specified socket. 

1 3 RCVOOB Receive out-of-band messages on a specified socket. 

23 SELECT Check the I/O status of the network sockets. 

9 SEND Send data on a specified socket. 

14 SENDOOB Send out-of-band messages on a specified socket. 
2 5 SETSOCKOPT Set options associated with sockets . 

7 SHUTDOWN Shutdown part or all of a full duplex logical link con- 

nection. 

24 SIOCTL Control the operations of open sockets. 

15 SOCKADDR Retrieve information set by the BIND call for the spec- 

ified socket. 
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6.7.1 ABORT 
NAME 

ABORT - disconnect all logical links (if any) and detach sockets that do not have the 
option SO KEEP ALIVE set. 

IOCB Data Members 



Bytes 



lo 



hi 



lo 



hi 



lo 



hi 



lo 



hi 



lo 



hi 



Data Fields: Input or Output 

+ < + 

| io f code : ABORT ( 10 ) j 

■ + ; 
! io socket: (not used) j 

+ I ; 

! v ; 

+ i 

I io flags : (not used) | 

+ i i 

I v i 

■+ I 

I io status: (not used) i 

+ I I 

I v i 

'+ I 

I io errno: (not used) | 

+ j : 

I v S 

■+ ! 

] io psize: (not used) < + 

• + I 

I v 

■ + 

I < + 

•+ i 

I I 

Data structure: none ! 

| 

| < - - + 

■ + 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The ABORT call disconnects all logical links (if any) and detaches the sockets that do 

not have the option SO KEEP ALIVE set. Refer to Section 6.7.17 for a discussion of 

SO_KEEP ALIVE. 

NOTE 

Before you can terminate a connection over a socket with the option 
SO_KEEPALIVE set, you must first issue a SETSOCKOPT call with 
SO_KEEPALIVE turned off. To turn off SO__KEEPALIVE, you must 
precede SO_KEEPALIVE with the NOT operator. (NOT 
SO_KEEPALIVE is the default condition.) 

You are then able to issue the ABORT call. The logical links (if any) are 
disconnected, and the socket is detached. However, if you issue 

ABORT without turning off SO KEEPALIVE, the socket remains 

attached, and the links (if any) stay active. 

Input Data 



io /code 

io socket 

io_flags 
io psize 



specifies ABORT as the function code. It has a decimal value of 10. 

specifies the socket number created by the ACCEPT or the 
ATTACH call. It is not used with the ABORT call. All logical links 
are disconnected by the ABORT call. 

defines specific flag options. You must set this data member to 0. It 
is not used with the ABOR T call. 

specifies the size of a data structure. This data member is not used 
with the ABORT call. 



Output Data 

There is no output data for the ABORT call. 



6-14 



DECnet-DOS Programmer's Reference Manual 



6.7.2 ACCEPT 
NAME 

ACCEPT - accept an incoming connection request on a socket and return a socket num- 
ber. 

IOCB Data Members 



Bytes 

+ + 

i ! 
+ + 

i lo ! 
+ + 

! hi ! 
+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

! hi | 

+ + 

! | 
+ + 

+ + 



Data Fields: Input or Output 

< + 

io fcode: ACCEPT (5) | 

! 

io socket: socket number \ 

\ ! 

V ! 
io flags : (not used) j 

v I 

I 
I 

io status: for success, \ 
I or -1 if unsuccessful j 

V ! 

io errno: error detail, j 
| if status: -1 | 

v : 

io psize: 26 bytes < + 

V 

< + 

I 

Data structures: attach dn | 
(input) | 
sockaddr dn \ 
(output) I 

< + 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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CIOCB Data Members - For Asynchronous Mode 



Bytes 

+ + 

i ! 
+ + 

! lo ! 

+ + 

! hi 

+ + 

l lo j 

+ + 

! hi j 

+ + 

! lo ! 

+ + 

i hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 
+ + 

+ + 

+ + 

I lo | 

+ - - - + 

! hi j 

+ + 

I lo ! 

+ + 

I hi | 
+ + 



Data Fields: Input or Output 

< + 

io_fcode: ACCEPT (5) j 

I 

io socket: socket number ! 

I I 

V | 

i 

io flags: (asynchronous) ! 
i (callback) j 

V | CIOCB 

! HEADER 
io status: for success, ! 
| -1 if unsuccessful, j 

V -2 for pending status | 

i 

io.errno: error detail, j 
| if status: -1 j 

V I 

| 

io psize : 26 bytes < + 

V 

< + 

I 

Data structures: attach dn I 
( input ) 

sockaddr dn j 
(output) | 

< + 

< + 

offset | 

v I 
io callback j 
segment | 

v I 
< + 



CIOCB 
PARAMETER 
LIST 



CALLBACK 
ADDRESS 
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DESCRIPTION 



The ACCEPT 'call extracts the first connection request on the queue of pending connec- 
tions, creates a new socket with a new number having the same properties of the origi- 
nal listening socket. The original socket remains open. 

If the socket is set to nonblocking I/O, and there are no queued connection requests, 
io status will return a - 1 , and errno will contain EWOULDBLOCK. 

There can be two modes of accepting an incoming connection. They are immediate 
and deferred modes. These modes of acceptance are set via the SETSOCKOPT call. 
When immediate mode is in effect, the acceptance of the connection request takes 
place immediately. The deferred mode indicates that the server task completes the 
ACCEPT call without fully completing the connection to the client task. In this case, 
the server task can examine the access control or optional user data before it decides to 
accept or reject the connection request. The server task must then issue the 
SETSOCKOPT call with the appropriate reject or accept option. 

DESCRIPTION - For Asynchronous Mode 

The ACCEPT call extracts the first connection request on the queue of pending connec- 
tions, creates a new socket with a new number having the same properties of the origi- 
nal listening socket. The original socket remains open. When the asynchronous form of 
the ACCEPT call is used, it is possible that the call may not complete. If this occurs, 
there are two ways for you to check the status of the call: 

• A callback routine (if implemented) will be called upon completion of the call. 

• If there is no callback routine, you should poll for status. To do this, examine the 

io status field. A value of -2, or -1 may be returned. A value of -2 indicates 

pending (no change) status. When the ACCEPT call successfully completes, a value 

of is returned in the io status field. In addition, you can retrieve data from the 

sockaddr__dn data structure which is filled in by the ACCEPT call. 

If the call is unsuccessful, io status returns a value of -1 . Additional error detail 

will also be contained in io errno. For a description of these error messages, see 

the DIAGNOSTICS section. 

There can be two modes of accepting an incoming connection. They are immediate 
and deferred modes. These modes of acceptance are set via the SETSOCKOPT call. 
When immediate mode is in effect, the acceptance of the connection request takes 
place immediately. The deferred mode indicates that the server task completes the 
ACCEPT call without fully completing the connection to the client task. 

In this case, the server task can examine the access control or optional user data before 
it decides to accept or reject the connection request. The server task can then issue the 
SETSOCKOPT call with the appropriate reject or accept option. 
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Input Data 

io—fcode 
io socket 



io__ flags 



io psize 



attach_dn 



att socket 



specifies ACCEPT as the function code. It has a decimal value of 5. 

specifies the socket number to be assigned. If is specified, the net- 
work process assigns a socket number for you. If a nonzero value is 
specified, the network process assigns that value. The assigned socket 

number, returned to io socket, is used in subsequent send and 

receive calls. If the value is already in use, an error message, EBADF, is 
returned in io errno. 

defines specific flag options. You must set this data member to 0. It is 
not used with the synchronous form of the ACCEPT call. 

For Asynchronous Mode: You can set io_flags to MSG ASYNC 

and MSG CALLBACK . MSG ASYNC processes the asynchronous 

I/O form of the ACCEPT function call. MSG CALLBACK allows the 

network to issue a callback routine when the ACCEPT call completes. 
The hexadecimal value for each flag option is listed in Appendix A. 

specifies the larger size of the 2 data structures, attach dn and 

sockaddr_dn (26 bytes). The 2 data structures overlay each other: 
attach _dn is used for input and sockaddr_dn is used for output. 

specifies the attach function data structure. The structure contains the 
following data fields: 

defines the number for a socket which was created with the 
ATTACH call, bound to a name by the BIND call, and was set 
to listen for incoming connections by the LISTEN call. 



att__domain 
att type 

att_protocol 

att srp 

att supreq 

io callback 



specifies the communications domain as AF DECnet. 

specifies the socket type. For example, SOCK STREAM. 

(See Appendix A for a list of defined socket types.) 

specifies the DECnet option for the socket. For example, 
DNPROTO_NSP. (See Appendix A for details.) 

specifies the socket recovery period. This data member is not 
used with the A TTACH call. 

specifies the support requirements. This data member is not 
used with the A TTACH call. 

For Asynchronous Mode: If the MSG CALLBACK bit is set 

in io_flags, then io callback specifies the 4 byte address of 

the function to be called by the network process when the 
function completes. (See Appendix B on how the data type 
exptr is formatted.) 
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Output Data 

io status 



to errno 



sockaddr_dn 



sdn_family 
sdn objnum 

sdn objnamel 

sdn objname 

sdn add 



upon successful completion. If an error occurs, io status 

returns a -1 . io errno will also contain additional error detail. 

For Asynchronous Mode: If the call's status is still pending, a 
value of -2 is returned, io status will return a upon success- 
ful completion. If an error occurs, io status will return a -1. 

io errno will also contain additional error detail. 

additional error detail if io status returns a -1 . (See the DIAG- 
NOSTICS section for a list of error conditions.) 

specifies the socket address data structure. A user retrieves data 
from the fields filled in by this function call. (See Appendix B on 
how sockaddr_dn is formatted.) 

For Asynchronous Mode: A user cannot retrieve data from the 

socket address data structure until io status has changed from 

a pending condition (-2) to successful completion (0). 

The following data fields are filled in by this function call: 
is the address family AF DECnet. 

is the object number for the client node. It can be a number 
to 255- 

is the size of the object name. 

is the object name of the client network task. It can be up to a 
16-byte array. It is used only when sdn_objnum equals 0. 

is the node address structure for the client task. (See Appen- 
dix B on how dn naddr is formatted.) 



Data Structure Type Summary 


sdn_family 


2 bytes 


sdn objnum 


1 byte 


sdn objnamel 


2 bytes 


sdn objname 


16-byte array 


sdn add 


4 bytes 


att socket 


2 bytes 


att domain 


2 bytes 


att type 


2 bytes 


att__protocol 


2 bytes 
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att srp 

att supreq 

DIAGNOSTICS 

[EBADF] 

[ECONNABORTED] 

[EEXIST] 
[EMFILE] 

[EWOULDBLOCK] 



2 bytes 
2 bytes 



The argument to socket does not contain a valid socket 

number. 

The client task disconnected before the ACCEPT call com- 
pleted. 

The socket number is already in use. 

There are no more available sockets. 

The socket is marked for nonblocking and no connections 
are waiting to be accepted. 

EWOULDBLOCK is not a valid error message for the asyn- 
chronous form of the ACCEPT call. 
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6.7.3 ATTACH 
NAME 

ATTACH - create a socket and attach a socket number. 
IOCB Data Members 



Bytes 



Data Fields: Input or Output 



lo 



hi 



lo 
hi 



lo 



hi 



lo 



hi 



lo 



hi 



io code: ATTACH (0) 
io socket : socket number 
V 

io flags : (not used) 

j 

V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno : error detail, 
! if status: -1 

V 

io psize: 12 bytes < 

I 

V 



+ 

! < 



Data structure: attach dn 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 

The ATTACH call creates a socket and attaches a socket number. 
Input Data 

specifies A TTACH as the function code. It has a decimal value of 0. 



io_fcode 
io socket 



io_flags 

io_psize 
attach dn 

att socket 



specifies the socket number to be assigned. If is specified, the net- 
work process assigns a socket number for you, and returns this num- 
ber to io socket. If a nonzero value is specified, the network process 

assigns that value. The assigned socket number is used in subsequent 
network calls. 

defines specific flag options. You must set this data member to 0. It is 
not used with the ATTACH call. 

specifies the size of the data structure attach _dn as 12 bytes. 

specifies the attach function data structure. The structure contains the 
following data fields: 

specifies the socket number. This data field is ignored by the 
ATTACH call. 



att_domain specifies the communications domain as AF DECnet. 

att type specifies the socket type. For example, SOCK STREAM. 

(See Appendix A for a list of defined socket types.) 

att_protocol specifies the DECnet option for the socket. For example, 

DNPROTO_NSP. (See Appendix A for details.) 

att srp specifies the socket recovery period. This data member is not 

used with the A TTACH call. 

att supreq specifies the support requirements. This data member is not 

used with the A TTACH call. 



Output Data 

io status 

io errno 



upon successful completion. If an error occurs, io status returns a 

-1 . io errno will also contain additional error detail. 

additional error detail if io status returns a -1. (See the DIAGNOS- 
TICS section for a list of error conditions.) 
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Data Structure Type Summary 



att socket 2 bytes 

att_domain 2 bytes 

att type 2 bytes 

att_protocol 2 bytes 

att srp 2 bytes 

att supreq 2 bytes 

DIAGNOSTICS 

[EEXIST] The socket number is already in use. 

[EINVAL] The argument io socket does not contain a valid socket num- 
ber. (You cannot assign -1 or -2 as socket numbers.) 

[EMFILE] There are no more available sockets. 

[ENOBUFS] No buffer space is available. The socket cannot be created. 
There are no more available logical links. 
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6.7.4 BIND 
NAME 

BIND - assign an object name or number to a socket. 
tOCB Data Members 



Bytes 

+ + 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo ! 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 
+ + 

+ + 

+ + 



Data Fields: Input or Output 

< 

iofcode: BIND (2) 

io socket : socket number 

V 

io flags: (not used) 
V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno: error detail, 
j if status: -1 

V 

io psize: 26 bytes < 

i 

V 

< 

Data structure: sockaddr dn 

< 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The BIND call assigns an object name or number to a socket. When a socket is first cre- 
ated with the ATTACH call, it exists in a name space but has no assigned name. The 
BIND call is used primarily by server tasks. The object name is required before a server 
task can listen for incoming connection requests using the LISTEN call. It can also be 
used by client tasks to identify themselves to server tasks. See also ACCEPT (Section 
6.7.2), CONNECT (Section 6.7.6), PEERADDR (Section 6.7. 1 1) and SOCKADDR (Sec- 
tion 6.7.20). 

NOTE 

The VAX/VMS proxy access by user name is made possible, if the client 
task uses the BIND call specifying his user name as the object name. 

You should refer to the SO REUSEADDR option of the SETSOCKOPT 

call if you wish to make more than one proxy connection with the 
same name. 



Input Data 

to_fcode 
to socket 

io_flags 

to psize 

sockaddr_dn 



sdn_family 
sdn_flags 
sdn objnum 

sdn objnamel 

sdn objname 

sdn_add 



specifies BIND as the function code. It has a decimal value of 2. 

specifies the number for a socket which has been created by the 
ATTACH call. 

defines specific flag options. You must set this data member to 
. It is not used with the BIND call . 

specifies the size of the data structure sockaddr_dn as 26 
bytes. 

specifies the socket address data structure. A user fills in the 
data for each field. The same data members must be used with 
the ACCEPT call. 

The following data fields can be modified: 

specifies the address family as AF DECnet. 

specifies the object flag option. It must be set to 0. 

defines the object number for this network task. It can be a 
number to 255. 

is the size of the object name. 

defines the object name of this network task. It can be up to a 
16-byte array. It is used only when sdn objnum equals 0. 

specifies the node address structure for this network task. 
This data member is ignored. 
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Output Data 

io status 

io errno 



returns a upon successful completion. If an error occurs, io status 

returns a - 1 . io errno will also contain additional error detail. 

returns additional error detail if io status returns a - 1 . (See the DIAG- 
NOSTICS section for a list of error conditions.) 



Data Structure Type Summary 



sdn_family 
sdn_flags 

sdn objnum 

sdn objnamel 

sdn objname 

sdn add 

DIAGNOSTICS 
[EADDRINUSE] 
[EBADF] 



2 bytes 
1 byte 

1 byte 

2 bytes 
16-byte array 
4 bytes 

The specified name is already used by another socket. 

The argument io socket does not contain a valid socket num- 
ber. 



[EINVAL] 



An invalid length for the object name was specified. 
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6.7.5 CANCEL 
NAME 

CANCEL - cancel a previous asynchronous function call request. 
IOCB Data Members 



Bytes 

+ + 

i i 
+ + 

! lo I 

+ + 

I hi | 

+ + 

I lo j 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi ! 

+ + 

! lo i 

+ + 

I hi i 
+ + 

! i 
+ + 

I I 
+ + 



Data Fields: Input or Output 

< - + 

io fcode: CANCEL (20) 

io socket: socket number, 

| except to cancel SELECT, socket 

V number must equal 0. 

io flags : (not used) 

i 
i 

V 

io status: for success, i 
| or -1 if unsuccessful 

V ! 

I 

io errno: error detail, j 
i if status: -1 j 

V I 

io psize: 4 bytes < + 

! 

V 

< + 

j 

Data structure: io buffer j 
< - + 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The CANCEL call allows a network process to cancel a previous asynchronous I/O 
request. This function call is used with the asynchronous form of the ACCEPT, RCVD, 
RCVOOB, SELECT and SEND function calls. To cancel a previous function request, you 
must specify the socket number for that call. If you want to cancel a SELECT call, the 
socket number must be set to 0. Otherwise, the call will not be cancelled. 

There are two return values for any cancel operation: 

• When a function call is cancelled, the CANCEL function always returns success. It 
does not matter whether the previous request existed, already completed or still in 



• To determine if the previous request was found and successfully cancelled, you 
must examine io errno for that particular call. An error code of EINTR will indi- 
cate successful cancellation. (See the DIAGNOSTICS section for each applicable 
function call.) 



progress. 



Input Data 



io code 



specifies CANCEL as the function code. It has a decimal value of 20. 



io socket 



specifies the socket number that must match the socket number for 
the call to be cancelled. 



io_flags 



defines specific flag options. You must set this data member to 0. It 
is not used with the CANCEL call. 



io psize 



specifies the size of a data structure. This data member is not used 
with the CANCEL call. 



Output Data 



io status 



returns a upon successful completion. 

specifies additional error detail. This data member is not used with 
the CANCEL function. 



io errno 
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6.7.6 CONNECT 
NAME 

CONNECT - initiate a connection request on a socket. 
IOCB Data Members 



Bytes 

+ + 

i I 

+ + 

| lo | 

+ + 

! hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 
+ + 

+ + 

+ + 



Data Fields: Input or Output 

< 

iofcode: CONNECT (4) 

io socket : socket number 

V 

io flags: (not used) 

i 

V 

io status : for success, 

| or -1 if unsuccessful 

V 

io errno: error detail, 
| if status: -1 

V 

io psize: 26 bytes < 

V 

< 

Data structure: sockaddr dn 



j IOCB 
! HEADER 



IOCB 
PARAMETER 
LIST 
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CIOCB Data Members - For Asynchronous Mode 



Bytes 

+ + 

i i 
i 1 

+ + 

! lo j 

+ + 

I hi i 

+ + 

i lo | 

+ + 

I hi i 

+ + 

j lo | 

+ + 

i hi | 

+ + 

! lo I 

+ + 

I hi | 

+ + 

I lo | 

+ - - + 

! hi | 
+ + 

+ + 

i ] 
i I 

+ + 

i lo | 
+ + 

I hi | 
+ + 

I lo | 
+ - + 

I hi | 
+ + 



Data Fields: Input or Output 



io_fcode: CONNECT (4) 



io socket: socket number 



io flags: (asynchronous) 

j (callback) 
V 

io status: for success, 

| -1 if unsuccessful, 

V -2 for pending status 

io errno: error detail, 

| if status: -1 
V 



io psize: 26 bytes < 
V 

< 



< 

< 

offset 



segment 



io callback 



Data structure: sockaddr dn 



CIOCB 
HEADER 



CIOCB 
PARAMETER 
LIST 



CALLBACK 
ADDRESS 
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DESCRIPTION 



The CONNECT call issues a connection request to another socket. Optional data as well 
as access control information (if any) are passed to the peer task as a result of this func- 
tion call. This data must be previously set by the SETSOCKOPT call. If subsequent CON- 
NECT calls are issued on the same socket, a task must reissue the SETSOCKOPT call to 
set up new optional data and/or access control information. 

NOTE 

Subsequent connection requests cannot be made on the same socket 
until it has been disconnected. 

If nonblocking I/O mode is set, and the CONNECT call is issued, the call returns immedi- 
ately with an error status, EINPROGRESS. 

DESCRIPTION - For Asynchronous Mode 

The CONNECT 'call issues a connection request to another socket. Optional data as well 
as access control information (if any) are passed to the peer task as a result of this func- 
tion call. This data must be previously set by the SETSOCKOPT call. If subsequent CON- 
NECT calls are issued on the same socket, a task must reissue the SETSOCKOPT call to 
set up new optional data and/or access control information. 

When the asynchronous form of the CONNECT call is used, it is possible that the call 
may not complete. If this occurs, there are two ways for you to check the status of the 
call: 

• A callback routine (if implemented) will be called upon completion of the call. 

• If there is no callback routine, you should poll for status. To do this, examine the 

to status field. A value of -2, or -1 may be returned. A value of -2 indicates 

pending (no change) status. When the CONNECT call successfully completes, a 
value of is returned in the to status field. 

If the call is unsuccessful, to status returns a value of -1. Additional error detail 

will also be contained in to errno. For a description of these error messages, see 

the DIAGNOSTICS section. 

Input Data 

io_fcode specifies CONNECT 'as the function code. It has a decimal value of 4 . 

to socket specifies the number for the socket which has been created by the 

ATTACH call. This socket number is used for establishing a connec- 
tion between the user tasks. It is also used with subsequent send and 
receive function calls. 

io___flags defines specific flag options. You must set this data member to 0. It 

is not used with the synchronous form of the CONNECT call. 
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io psize 

sockaddr_dn 



sdn_family 
sdn__flags 
sdn objnum 



For Asynchronous Mode: You can set io_flags to MSG ASYNC 

and MSG CALLBACK. MSG ASYNC processes the asynchronous 

I/O form of the CONNECT function call. MSG CALLBACK allows 

the network to issue a callback routine when the CONNECT call 
completes. The hexadecimal value for each flag option is listed in 
Appendix A. 

specifies the size of the data structure sockaddr_dn as 26 bytes. 

specifies the socket address data structure. A user fills in the data for 
each field. (See Appendix B on how sockaddr_dn is formatted.) 

The following data fields can be modified: 

specifies the address family as AF DECnet. 

specifies the object flag option. It must be set to 0. 

defines the object number for the server task. It can be a num- 
ber to 255. 



sdn objnamel 

sdn objname 

sdn add 



is the size of the object name. 

defines the object name of the server network task. It can be 
up to a 16-byte array. It is only used when sdn^jobjnum 
equals 0. 

specifies the node address structure for the server task. (See 
Appendix B on how dn naddr is formatted.) 

io callback For Asynchronous Mode: If the MSG_CALLBACK bit is set 

in io__flags, then io callback specifies the 4 byte address of 

the function to be called by the network process when the 
function completes. (See Appendix B on how the data type 
exptr is formatted.) 



Output Data 

io status 



returns a upon successful completion. If an error occurs, 

io status returns a -1 . io errno will also contain additional error 

detail. 

If the socket is set to nonblocking I/O, and you issue a CONNECT, 
the function returns a value of -1 and the error message, 
EINPROGRESS. 

For Asynchronous Mode: If the call's status is still pending, a value 
of -2 is returned, io status will return a upon successful comple- 
tion. If an error occurs, io status will return a -1. io errno will 

also contain additional error detail. 
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to errno 

Data Structure Type 

sdn_family 
sdn_flags 

sdn objnum 

sdn objnamel 

sdn objname 

sdn add 

DIAGNOSTICS 
[EAFNOSUPPORT] 

[EBADF] 

[EBUSY] 

[ECONNABORTED] 

[ECONNREFUSED] 

[ECONNRESET] 

[EHOSTUNREACH] 

[EINPROGRESS] 

[EINVAL] 

[ENETDOWN] 

[ENETUNREACH] 

[ERANGE] 

[ESRCH] 
[ETIMEDOUT] 

[ETOOMANYREFS] 



returns additional error detail if io status returns a -1 . (See the 

DIAGNOSTICS section for a list of error conditions.) 

Summary 

2 bytes 
1 byte 

1 byte 

2 bytes 
16-byte array 
4 bytes 



Addresses in the specified address family cannot be 
used with this particular socket. 

The argument io socket does not contain a valid 

socket number. 

The socket is not in idle state. The socket is in the pro- 
cess of being connected or disconnected; the socket is a 
connected or listening socket. 

The peer task has disconnected and the connection was 
aborted. 

The attempt to connect was forcefully rejected. 

The remote task has failed. 

The remote node is unreachable. 

The connection request is now in progress. 

The object name of the server task is too long. 

The network is down. 

The network cannot be reached from this host. 

The object number of the server task is invalid. The 
valid range is to 255. 

The server object does not exist on the remote node. 

Connection establishment was timed out before a con- 
nection was established. 

The remote node has accepted the maximum number of 
connection requests. 
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6.7.7 DETACH 



NAME 

DETACH - disconnect all associated active logical links, and detach the specified 
socket and any associated sockets, only if the option SO KEEPALIVE is not set. 

IOCB Data Members 



Bytes 

+ + 

I I 

+ + 

I lo | 

+ + 

i hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo ! 

+ - - + 

I hi | 

+ + 

I lo | 

+ + 

| hi | 

+ + 

I lo ! 

+ + 

I hi | 

+ - - + 

| i 

+ + 

I I 

+ + 



Data Fields: input or Output 

< + 

io fcode: DETACH (1) | 

io socket: socket number j 

V j 

io flags : (not used) 

I i 

V ; 

io status: for success, j 
! or -1 if unsuccessful I 

v i 

io errno: error detail, | 
j if status: -1 j 

V j 

io psize: not used < + 

I 

V 

< + 

i 

Data structure: none i 

j 

! 

< + 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The DETACH call disconnects all associated active logical links, and detaches the speci- 
fied socket if it does not have the option SO KEEP ALIVE set. 

NOTE 

Before you can terminate a connection over a socket with the option 
SO__KEEP ALIVE set, you must first issue a SETSOCKOPT call with 
SO_KEEP ALIVE turned off. To turn off SO_KEEPALIVE, you must 
precede SO_KEEP ALIVE with the NOT operator. (NOT 
SO_KEEPALIVE is the default condition.) 

You are then able to issue the DETACH call. The logical links (if any) 
are disconnected, and the socket is detached. However, if you issue 
DETACH without turning off SO_KEEPALIVE, the socket remains 
attached, and the links (if any) stay active. 



Input Data 

iO—fcode 

io socket 

io_flags 

io^size 

Output Data 

io status 

io errno 

DIAGNOSTICS 

[EBADF] 



specifies DETACH as the function code. It has a decimal value of 1 . 

specifies the socket number created by the ACCEPT or ATTACH call. 

defines specific flag options. You must set this data member to 0. It is 
not used with the DETACH call. 

specifies the size of a data structure. This data member is not used 
with the DETACH call. 



returns a upon successful completion. If an error occurs, io status 

returns a -1 . io errno will also contain additional error detail. 

returns additional error detail if io status returns a -1 . (See the DIAG- 
NOSTICS section for a possible error condition.) 



The argument io socket does not contain a valid socket number. 
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6.7.8 DISCONNECT 
NAME 

DISCONNECT - disconnect socket from the peer socket, and terminate the logical link 
connection. 

IOCB Data Members 



Bytes 

+ + 

+ + 

i lo ; 
+ + 

S hi i 

+ + 

j lo | 

+ + 

I hi i 

+ + 

i lo | 

+ + 

i hi | 

+ + 

i lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi ! 
+ + 

+ + 

+ + 



Data Fields: Input or Output 

< + 

iofcode: DISCONNECT (6) | 

i 

io socket : socket number j 

; i 
! i 

V I 

j 

io flags : (not used) j 

i I 

V I IOCB 

j HEADER 

io status: for success, | 
| or -1 if unsuccessful j 

V | 

io errno: error detail, | 
| if status: -1 | 

V I 

io psize: not used < - + 

V 

< - + 

I 

Data structure: none | 

i 

< - - + 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The DISCONNECT call disconnects the socket from the peer socket, and terminates the 
logical link. 



Before you can terminate a connection over a socket set with the 
option SO_KEEP ALIVE, you must first issue a SETSOCKOPT call with 
the SO_KEEP ALIVE option turned off. That is, precede the 
SO__KEEPALIVE with the NOT operator. Then issue the DISCON- 
NECT function call and the connection is completely broken. 

The effect of DISCONNECT on unsent data queued for a remote task depends on the lin- 
ger option set with the SETSOCKOPT function call. (See Section 6.7.17) If 

SO LINGER is set, control is returned to the task, but the link is not disconnected until 

the unqueued data is sent. If SO DONTLINGER is set, control is returned to the task, 

and any unqueued data is lost. 

Input Data 

io_fcode specifies DISCONNECT as the function code. It has a decimal value 



NOTE 



of 6. 



io socket 



specifies the socket number created by the ACCEPT or ATTACH 
call. 



io_J7ags 



defines specific flag options. You must set this data member to 0. It 
is not used with the DISCONNECT call. 



io__psize 



specifies the size of a data structure. This data member is not used 
with the DISCONNECT call . 



Output Data 



to status 



returns a upon successful completion. If an error occurs, 

to status returns a -1 . io errno will also contain additional error 

detail. 



io errno 



returns additional error detail if io status returns a -1. (See the 

DIAGNOSTICS section for a possible error condition.) 



DIAGNOSTICS 



[EBADF] 



The argument io socket does not contain a valid socket number. 
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6.7.9 LISTEN 
NAME 

LISTEN - listen for pending connections on a socket. 
IOCB Data Members 



Bytes 

+ + 

i I 
+ + 

i lo | 

+ + 

i hi | 

+ + 

I lo I 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

! hi | 
+ + 

+ + 

+ + 



Data Fields: Input or Output 

< - 

io fcode: LISTEN (3) 

io socket : socket number 

V 

io flags: (not used) 
V 

io status: for success, 

! or -1 if unsuccessful 

V 

io errno: error detail, 
| if status: -1 

V 

io psize: 2 bytes < 

V 

< 

Data structure: listen dn 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The LISTEN call declares your socket as a server which is available for client connec- 
tions. The server must use a bound name or number in order to listen for incoming cli- 
ent connections. This call must be issued before an incoming connection can be 
accepted or rejected. See also the ACCEPT (Section 6.7.2) and the SELECT (Section 
6.7.14) calls. 

If you detach a listening socket while the socket is receiving client connections, then all 
links associated with the listening socket immediately abort and all outstanding data is 
lost. 



Input Data 

io^Jcode 
io socket 

io_flags 

io psize 

listen_dn 



Isn backlog 



Output Data 

io status 

io errno 



specifies LISTEN is the function code. It has a decimal value of 3. 

specifies number for a socket which has been created by the 
ATTACH call and bound to a name by the BIND call. 

defines specific flag options. You must set this data member to 0. It 
is not used with the LISTEN call. 

specifies the size of the data structure listen dn as 2 bytes. 

specifies the listen data structure. (See Appendix B on how 
listen_dn is formatted.) The structure contains the following data 
field: 

defines the total maximum number of unaccepted incoming 
connects which are allowed on this particular socket. The maxi- 
mum allowable number of incoming connects is 5 . If a connec- 
tion request arrives when the queue is full, the client task will 
receive an error with an indication of ECONNREFUSED. 



returns a upon successful completion. If an error occurs, 

io status returns a -1 . io errno will also contain additional error 

detail. 

returns additional error detail if io status returns a -1. (See the 

DIAGNOSTICS section for a list of error conditions.) 



Data Structure Type Summary 



Isn backlog 

DIAGNOSTICS 

[EBADF] 



2 bytes 



The argument io socket does not contain a valid socket num- 
ber. 



[EOPNOTSUPP] 



The specified socket type does not support the listen operation. 
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6.7.10 LOCALINFO 
NAME 

LOCALINFO - retrieve network information for the local node. 
IOCB Data Members 



Bytes 

+ + 

I | 

+ + 

I lo I 

+ + 

j hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ - - + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

i lo | 

+ + 

! hi | 

+ + 

! | 

+ + 

I . I 

+ + 



Data Fields: Input or Output 

< 

iofcode: LOCALINFO (22) 

io socket: not used 

I 

v 

io flags : (not used) 
V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno : error detail, 
| if status: -1 

V 

io psize: 20 bytes <-- 

V 

< 

Data structure: localinfo dn 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The LOCALINFO call retrieves network information for the local node. It returns the 
software version number for the network process; the local node name and address; 
and the maximum possible segment buffer size which can be used on a logical link. It 
also returns the number of sockets available for data exchange, and the current DECnet 
database device and path. 

NOTE 

The localinfo_dn data structure format differs from the format that 
appeared in DECnet-DOS VI .0. 

Input Data 

io__fcode 



io socket 

io_flags 

io__psize 
Output Data 

io status 

io errno 

localinfo_dn 



specifies LOCALINFO as the function code. It has a decimal value of 
22. 

specifies the socket number. It is not used with the LOCALINFO call. 

defines specific flag options. You must set this data member to 0. It is 
not used with the LOCALINFO call. 

specifies the size of the data structure localinfo dn as 20 bytes. 



returns a upon successful completion. If an error occurs, io status 

returns a -1 . io errno will also contain additional error detail. 

returns additional error detail if io status returns a -1. (See Appen- 
dix C for a list of error conditions.) 

specifies the local node information data structure. A user retrieves 
data from the fields filled in by this function call. (See Appendix B on 
how localinfo dn is formatted.) 



The following data fields can be filled in by this function call: 

is the software version number for the network process, 
is the node name for the local node, 
is the node address for the local node, 
is the buffer segment size to be used on the logical link, 
is the number of sockets available for data exchange. 
lcl—decnet_device is the DECnet database device. 

lcl__decnet path specifies the address of the buffer that contains the DECnet 

database path specification which includes the device name. 



Icl version 

lei nodename 

Icl nodeaddr 

Icl segsize 

Icl sockets 
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Data Structure Type Summary 

lei version 3-byte array 



lei nodename 

lei nodeaddr 

lei segsize 

lei sockets 

lcl___decnet___device 
lcl__jdecnet_path 



7-byte array 
2 bytes 
2 bytes 
1 byte 
1 byte 
4 bytes 
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6.7.11 PEERADDR 
NAME 

PEERADDR - get information about your peer socket. 
IOCB Data Members 



Bytes 

+ + 

I I 
+ + 

I lo ! 
+ + 

I hi I 
+ + 

i lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

| hi | 
+ + 

+ + 

+- + 



Data Fields: Input or Output 

< 

io^fcode: PEERADDR (16) 

io socket: socket number 

V 

io flags: (not used) 
V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno: error detail, 
| i f status : - 1 

V 

io psize: 26 bytes < 

V 

< 

Data structure: sockaddr dn 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 

The PEERADDR call returns information about your peer socket. 
Input Data 

io /code specifies PEERADDR as the function code. It has a decimal value of 

16. 

io socket specifies the number for the socket which has been created by the 

ACCEPT or ATTACH call. 

io__flags defines specific flag options. You must set this data member to 0. It is 

not used with the PEERADDR call. 

io psize specifies the size of the data structure sockaddr_dn as 26 bytes. 

Output Data 

io status returns a upon successful completion. If an error occurs, io status 

returns a -1 . io errno will also contain additional error detail. 

io errno returns additional error detail if io status returns a - 1 . (See the DIAG- 

NOSTICS section for a possible error condition.) 

sockaddr_dn specifies the socket address data structure. A user retrieves data from 
the fields filled in by this function call. (See Appendix B on how 
sockaddr_dn is formatted.) 



sdri— family 
sdn_objnum 

sdn objnamel 

sdri—objname 

sdn add 



The following data fields can be filled in by this function call: 
is the address family AF DECnet. 



is the object number for the peer task. It can be a number to 
255. 

is the size of the object name for the peer task. 

is the name of the peer network task. It can be up to a 16-ele- 
ment array. It is only used when sdn objnum equals 0. 

is the node address structure for the peer task. (See Appendix 
B on how dn naddr is formatted.) 
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Data Structure Type Summary 



sdn_family 2 bytes 

sdn objnum 1 byte 

sdn objnamel 2 bytes 

sdn objname 16-byte array 

sdn_add 4 bytes 
DIAGNOSTICS 

[EBADF] The argument to socket does not contain a valid socket number. 
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6.7.12 RCVD 
NAME 

RCVD - receive data on a specified socket. 
IOCB Data Members 



Bytes Data Fields: Input or Output 

+ + < + 

i i io_fcode: RCVD (8) | 

+ + | 

| lo io socket : socket number | 

+ + | | 

! hi i V | 

+ + | 

| lo | io flags: (peek message) | 

+ - + | (NEOM) | 

i hi j V | IOCB 

+ + j HEADER 

| lo | io status: -1 if unsuccessful, | 

+ + | - received message, zero | 

| hi | V length or logical link down, | 

+ + 1 if partial message received | 

| lo | io errno: error detail, j 

+ + | if status: -1 | 

! hi | V | 

+ + | 

| lo | io psize: user defined < - + 

+ + ! size of io buffer (input) 

| hi ! V number of bytes received (output) 

+ + 



| | j IOCB 

Data structure: io buffer | PARAMETER 

| LIST 

I 

| | < - - + 

+ + 
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CIOCB Data Members - For Asynchronous Mode 



Bytes 

+ + 

I I 

+ + 

! lo I 

+ + 

I hi | 

+ + 

I lo | 

+ + 

1 hi | 

+ + 

I lo ! 

+ + 

| hi I 

! I 

+ + 

! lo I 

+ + 

I hi j 

+ + 

I lo i 

+ + 

I hi | 
+ + 

i I 
+ + 

i I 
i I 

+ + 

I lo | 

+ + 

i hi | 

+ + 

| lo | 

+ + 

I hi | 
+ + 



Data Fields: Input or Output 

< 

iofcode: RCVD (8) 

io socket : socket number 

V 

io flags: (peek message) 
| (asynchronous) 

V (callback) j CIOCB 
(NEOM) i HEADER 

io status : -1 if unsuccessful 
| - received message, zero 

V length message or logical link 
down, -2 if pending, 1 if 
partial message received 

io errno: error detail, 
| if status: -1 

V 

io psize: user defined < + 

| size of io buffer (input) 

V number of bytes received (output) 



< 



Data structure: io buffer 



< 

< 

offset 

v 

segment 
v 



CIOCB 
PARAMETER 
LIST 



io callback 



CALLBACK 
ADDRESS 
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DESCRIPTION 



The RCVD call is used to receive data from your peer. If no messages are available at the 
socket, the RCVD call waits for a message to arrive unless the socket is nonblocking. In 
this case, a status of -1 is returned with the field to ermo set to EWOULDBLOCK. 

If the socket becomes disconnected, queued data can still be received from the broken 
logical link. However, if you shutdown the socket or detach it, queued data cannot be 
received. When the logical link is not in a connected state, and all data has been read, 
the RCVD call returns zero bytes. 

For sequenced sockets, you can read a single message with multiple calls into multiple 
buffers. (See Appendix A for a description of socket types.) To do this, set the io_flags 
field to MSG NEOM (not end of message). 

NOTE 

MSG NEOM is not a valid option for stream sockets. Stream mode 

destroys all record boundaries. 

For example, you want to receive a 300 byte message, but only specified a receive 
buffer of 100 bytes. Normally, the RCVD call would flush the rest of the message (after 

you read the first 100 bytes) and return a status of 0. Setting io_flags to MSG NEOM 

indicates that the caller does not want the remaining unread data to be flushed. If the 

user did not receive the entire message, to status returns a value of 1 . MSG NEOM 

allows you to issue another RCVD call and read the remaining 200 bytes of the buffer. 

In addition to flagging the RCVD call with MSG NEOM, you can also set the flags 

option to MSG PEEK. This option enables you to "peek" or read the next pending 

message without removing it from the receive queue. When the RCVD call is flagged 

with MSG PEEK and MSG NEOM, multiple RCVD calls can be made to peek at the 

entire message. You cannot peek at more than one message. 

The SELECT call may be used to determine when more data has arrived. (See Section 
6.7.14) 

DESCRIPTION - For Asynchronous Mode 

The RCVD call is used to receive data from your peer. If the socket becomes discon- 
nected, queued data can still be received from the broken logical link. However, if you 
shutdown the socket or detach it, queued data cannot be received. When the logical 
link is not in a connected state, and all data has been read, the RCVD call returns zero 
bytes. 

When the asynchronous form of the RCVD call is used, it is possible that the call may 
not complete. If this occurs, there are two ways for you to check the status of the call: 

• If the asynchronous form of the RCVD call is used, you can also specify that a call- 
back routine be used. The message option, MSG CALLBACK, allows the network 

to issue a callback routine when the RCVD call completes. 
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• If there is no callback routine, you should poll for status. To do this, examine the 

io status field. A value of -2, 0, -1 or 1 may be returned. A value of -2 indicates 

pending (no change) status. If a value of is returned, you need to see how the call 
was completed: If the message was received, the number of bytes sent by your peer 
is returned in to psize. Otherwise, a zero length message was received or the logi- 
cal link has been disconnected. 

A value of 1 indicates that a partial message was received. 

If the call is unsuccessful, io status returns a value of -1 . The error reason will be 

contained in io errno. For a description of error messages, see the DIAGNOSTICS 

section. 

For sequenced sockets, you can read a single message with multiple calls into multiple 
buffers. To do this, set the io_flags field to MSG NEOM (not end of message). 

NOTE 

MSG NEOM is not a valid option for stream sockets. Stream mode 

destroys all record boundaries. 

For example, you want to receive a 300 byte message, but only specified a receive 
buffer of 100 bytes. Normally, the RCVD call would flush the rest of the message (after 

you read the first 100 bytes) and return a status of 0. Setting io_flags to MSG NEOM 

indicates that the caller does not want the remaining unread data to be flushed. If the 

user did not receive the entire message, io status returns a value of 1. MSG NEOM 

allows you to issue another RCVD call and read the remaining 200 bytes of the buffer. 

In addition to flagging the RCVD call with MSG NEOM, you can also set the flags 

option to MSG PEEK. This option enables you to "peek" or read the next pending 

message without removing it from the receive queue. When the RCVD call is flagged 

with MSG PEEK and MSG NEOM, multiple RCVD calls can be made to peek at the 

entire message. You cannot peek at more than one message. 

The SELECT call may be used to determine when more data has arrived. (See Section 
6.7.14) 

Input Data 

io_fcode specifies RCVD as the function code. It has a decimal value of 8. 

io socket specifies the number for a socket created by the A CCEPT or A TTA CH 

call. 

io_flags defines specific flag options . You can set this field to for reading nor- 

mal messages. To read the next pending message without removing it 

from the receive queue, set the io_flags field to MSG PEEK. To 

receive a single message having multiple parts, set the io_flags field 

to MSG NEOM. The hexadecimal value for each flag option is listed 

in Appendix A. 
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io psize 

io buffer 

io callback 

Output Data 

io buffer 

io psize 

io status 



For Asynchronous Mode: You can set this data member to 
MSG ASYNC and MSG CALLBACK for implementing asynchro- 
nous callback routines. MSG ASYNC processes the asynchronous 

I/O form of the RCVD function call. MSG CALLBACK allows the net- 
work to issue a callback routine when the RCVD call completes. In 
addition to asynchronous callbacks, you can set the io_Jlags to 

MSG PEEK and/or MSG NEOM. MSG PEEK allows you to read the 

next pending message without removing it from the receive queue. 

MSG NEOM allows you to receive a single message in multiple parts. 

The hexadecimal value for each flag option is listed in Appendix A. 

specifies the size of the user defined buffer. 

specifies the address for the buffer which contains the incoming mes- 
sage. (Refer to Appendix B on how io buffer is formatted.) 

For Asynchronous Mode: If the MSG— CALLBACK bit is set in 
io_flags, then io callback specifies the 4 byte address of the func- 
tion to be called by the network process when the function com- 
pletes. (See Appendix B on how the data type exptr is formatted.) 



is the address for the buffer which will contain the incoming message. 
(Refer to Appendix B on how io buffer is formatted.) 

specifies the number of transferred bytes upon successful completion. 

If status returns a 0, the message was received. (Check io psize for 

the number of transferred bytes.) Otherwise, you have received a zero 
length message, or the logical link has been disconnected. To deter- 
mine the state of the logical link, use the GETSOCKOPT function call 

with the DSO LINKINFO option (See Section 6.7.17). If the link has 

been disconnected, then all subsequent receives will return zero 
bytes. 

If an error occurs, io status returns a -1 . io errno will also contain 

additional error detail. 

For Asynchronous Mode: If the call's status is still pending, a value of 
-2 is returned. If status returns a 0, the message was received. (Check 

io psize for the number of transferred bytes.) Otherwise, you have 

received a zero length message, or the logical link has been discon- 
nected. To determine the state of the logical link, use the 
GETSOCKOPT function call with the DSO^LINKINFO option (See 
Section 6.7. 17). If the link has been disconnected, then all subsequent 
receives will return zero bytes. 
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If an error occurs, to status returns a -1 . to errno will also contain 

additional error detail. 

to errno returns additional error detail if to status returns a - 1 . (See the DIAG- 

NOSTICS section for a list of error conditions.) 

If you receive a zero length message, to errno will return a 1 . 

Data Structure Type Summary 

to buffer 4 bytes 

to callback 4 bytes 

DIAGNOSTICS 

When receiving normal data, the following set of error messages can occur: 
Blocking I/O 

Description 



Message 

[EBADF] 

Nonblocking I/O 

[EBADF] 



The argument to socket does not contain a valid socket num- 
ber. 



The argument to socket does not contain a valid socket num- 
ber. 



[EWOULDBLOCK] The receive operation would block because there is currently 
no data to receive. 

EWOULDBLOCK is not a valid error message for the asynchro- 
nous form of the RCVD call. 
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6.7.13 RCVOOB 
NAME 

RCVOOB - receive out-of-band messages on a specified socket. 
IOCB Data Members 



Bytes 

+ + 

I I 
+ + 

I lo | 

+ + 

i hi | 

+ + 

! lo I 

+ + 

I hi | 

+ - + 

I lo | 

+ + 

I hi | 

+ - + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

! ! 

+ + 

I I 

I I 
+ + 



Data Fields: Input or Output 

< 

io_fcode: RCVOOB (13) 

io socket: socket number 

V 

io flags: (peek message) 
V 

io status: -1 if unsuccessful, 
| - received message, 

V zero length message or 

logical link down 

io errno: error detail, 
| if status: -1 

V 



io psize : user defined < + 

| size of io buffer (input) 

V number of bytes received (output) 



Data structure: io buffer 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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CIOCB Data Members - For Asynchronous Mode 
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Data Fields: Input or Output 

< - 

iofcode: RCVOOB (13) 

io socket : socket number 

V 



io flags : 

i 
i 

V 

io status 



(peek message) 
( asynchronous ) 
( callback ) 



2 for pending 
| status, -1 if 

V unsuccessful, - received 
message, zero length message 
or logical link down 
io errno: error detail, 
| if status: -1 

V 



CIOCB 
HEADER 



io psize: user defined < + 

| size of io buffer (input) 
V number of bytes received (output) 



Data structure: io buffer 



< 

< 

offset 
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DESCRIPTION 



The RCVOOB call is used to receive out-of-band data from another socket. Out-of- 
band messages are delivered to a receiving task ahead of normal messages. If the socket 
is set to nonblocking I/O, and there is no data to receive, a status of -1 is returned with 
the field io__errno set to EWOULDBLOCK. 

NOTE 

This occurs whether or not the socket is in blocking or nonblocking 
mode. 

If the socket becomes disconnected, queued data can still be received from the broken 
logical link. However, if you shutdown the socket or detach it, queued data cannot be 
received. When the logical link is not in a connected state, and all data has been read, 
the RCVOOB call will not return. 

The SELECT call may be used to determine when more data has arrived. (See Section 
6.7.14) 

DESCRIPTION - For Asynchronous Mode 

The RCVOOB call is used to receive out-of-band data from another socket. Out-of-band 
messages are delivered to a receiving task ahead of normal messages. 

When the asynchronous form of the RCVOOB call is used, it is possible that the call 
may not complete. If this occurs, there are two ways for you to check the status of the 
call: 

• If the asynchronous form of the RCVOOB call is used, you can also specify that a 
callback routine be used. The message option, MSG CALLBACK, allows the net- 
work to issue a callback routine when the RCVOOB call completes. 

• If there is no callback routine, you can poll for status. To do this, examine the 

to status field. A value of -2, or -1 may be returned. A value of -2 indicates 

pending (no change) status. If status returns a 0, the message was received. (Check 
io_psize for the number of transferred bytes.) Otherwise, you have received a 
zero length message, or the logical link has been disconnected. 

If the call is unsuccessful, to status returns a value of -1. Additional error detail 

will also be contained in to errno. For a description of these error messages, see 

the DIAGNOSTICS section. 

If the socket becomes disconnected, queued data can still be received from the broken 
logical link. However, if you shutdown the socket or detach it, queued data cannot be 
received. When the logical link is not in a connected state, and all data has been read, 
the RCVOOB call will return but the function will not complete. The SELECT call may 
be used to determine when more data has arrived. (See Section 6.7. 1 4) 
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Input Data 

io_fcode 
io socket 

io_flags 



to— psize 
io buffer 

io callback 



Output Data 

io buffer 

io psize 

io status 



specifies RCVOOB as the function code. It has a decimal value of 1 3. 

specifies the number for a socket which has been created by the 
ACCEPT ot CONNECT call. 

defines specific flag options. You can set this field to MSG PEEK to 

read the next pending message without removing it from the receive 
queue. The hexadecimal value for each flag option is listed in Appen- 
dix A. 

For Asynchronous Mode: You can set this data member to 
MSG ASYNC and MSG CALLBACK for implementing asynchro- 
nous callback routines. MSG ASYNC processes the asynchronous 

I/O form of the RCVOOB function call. MSG CALLBACK allows the 

network to issue a callback routine when the RCVOOB call completes. 
In addition to asynchronous callbacks, you can set the io—flags to 
MSG PEEK which allows you to read the next pending message with- 
out removing it from the receive queue. The hexadecimal value for 
each flag option is listed in Appendix A. 

specifies the size of the user defined buffer. 

specifies the address for the buffer which contains the incoming out- 
of-band message. (Refer to Appendix B on how io buffer is format- 
ted.) 

For Asynchronous Mode: If the MSG_CALLBACK bit is set in 
io_flags, then to callback specifies the 4 byte address of the func- 
tion to be called by the network process when the function com- 
pletes. (See Appendix B on how the data type exptr is formatted.) 



is the address for the buffer which will contain the incoming out-of- 
band message. (Refer to Appendix B on how io buffer is formatted.) 

specifies the number of transferred bytes upon successful complt *> 

If status returns a 0, the message was received. (Check io psize fc 

the number of transferred bytes.) Otherwise, you have received a zero 
length message, or the logical link has been disconnected. To deter- 
mine the state of the logical link, use the GETSOCKOPT function call 

with the DSO LINKINFO option (See Section 6.7. 17). If the link has 

been disconnected, then all subsequent receives will return zero 
bytes. 

If an error occurs, io status returns a -1 . io errno will also contain 

additional error detail. 
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For Asynchronous Mode: If the call's status is still pending, a value of 
-2 is returned. If status returns a 0, the message was received. (Check 

io psize for the number of transferred bytes.) Otherwise, you have 

received a zero length message, or the logical link has been discon- 
nected. To determine the state of the logical link, use the 
GETSOCKOPT function call with the DSO_LINKINFO option (See 
Section 6.7. 17). If the link has been disconnected, then all subsequent 
receives will return zero bytes. 

If an error occurs, io status returns a -1 . io errno will also contain 

additional error detail. 

io errno returns additional error detail if io status returns a - 1 . (See the DIAG- 
NOSTICS section for a list of error conditions.) 

If you receive a zero length message, io errno will return a 1 . 

Data Structure Type Summary 

io buffer 4 bytes 

io callback 4 bytes 

DIAGNOSTICS 

When receiving out-of-band data, the following set of error messages can occur: 
Blocking I/O 

Message Description 

[EBADF] The argument io socket does not contain a valid socket num- 

ber. 

[EWOULDBLOCK] The receive operation would block because there is currently 
no data to receive. 

EWOULDBLOCK is not a valid error message for the asynchro- 
nous form of the RCVOOB call. 

Nonlocking I/O 

Message Description 

[EBADF] The argument io socket does not contain a valid socket num- 

ber. 

[EWOULDBLOCK] The receive operation would block because there is currently 
no data to receive. 

EWOULDBLOCK is not a valid error message for the asynchro- 
nous form of the RCVOOB call. 
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6.7.14 SELECT 
NAME 

SELECT - check the I/O status of the network sockets. 
IOCB Data Members 



Bytes 

+ + 
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I lo | 

+ + 

I hi | 

H + 
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H + 

I hi | 
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+ + 



Data Fields: Input or Output 

< + 

iofcode: SELECT (23) | 

io socket: (not used) j 

I i 

V I 

! 

io flags: (not used) j 

j I 
v I 

I 

io status: number of ! 
| descriptors, or | 

V -1 if unsuccessful ! 

S 

io errno: error detail, j 
| if status: -1 | 

V | 

i 

io psize: 16 bytes < + 

V 

< + 

Data structure: select dn j 
< + 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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CIOCB Data Members - For Asynchronous Mode 



Bytes 
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Data Fields: Input or Output 

< 

iofcode: SELECT (23) 

io socket: (not used) 

V 

io flags : 
V 



( asynchronous ) 
( callback ) 



io status: number of 

| descriptors, or 

V -1 if unsuccessful, 

-2 for pending status 

io errno : error detail, 
| if status: -1 

V 



io psize : 16 bytes 
V 

< - 



io callback 



Data structure: select dn 



< 

< 

offset 

v 

segment 
v 



CIOCB 
HEADER 



| CIOCB 
! PARAMETER 
! LIST 

i 

+ 
+ 



CALLBACK 
ADDRESS 
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DESCRIPTION 



The SELECT call checks the network sockets specified by the bit masks in the data struc- 
ture select_dn to see if they are ready for reading, writing, or have any outstanding 
out-of-band messages. 

The SELECT call does not tell you if the logical link has been broken. You should use 
the SELECT call to help manage your ACCEPT, SEND, SENDOOB, RCVD and RCVOOB 
calls. 

The I/O descriptors are long words which contain bit masks. Each bit in a mask repre- 
sents one socket number. For example, socket " 3 " is the fourth bit or has a hex value 
of 8. 

NOTE 

The SELECT call can only check socket numbers in the range to 3 1 . 

To specify the bit for any socket number, use the value created by the ATTACH or the 
ACCEPT call, as "/< <s". 

DESCRIPTION - For Asynchronous Mode 

The SELECT call checks the network sockets specified by the bit masks in the data struc- 
ture select__dn to see if they are ready for reading, writing, or have any outstanding 
out-of-band messages. 

The SELECT call does not tell you if the logical link has been broken. You should use 
the SELECT call to help manage y out ACCEPT, SEND, SENDOOB, RCVD and RCVOOB 
calls. 

The SELECT call examines the network sockets until the call timeouts (see 

sel seconds) or status is returned. If you specify multiple sockets to be examined, and 

one socket becomes detached, the SELECT call will return with the error message, 
EBADF. You must reissue the SELECT call in order to examine the remaining sockets. 

The I/O descriptors are long words which contain bit masks. Each bit in a mask repre- 
sents one socket number. For example, socket "3" is the fourth bit or has a hex value 
of 8. 

NOTE 

The SELECT call can only check socket numbers in the range to 3 1 . 

To specify the bit for any socket number, use the value created by the ATTACH or the 
ACCEPT call, as "2< <s". 

Input Data 

io_fcode specifies SELECT as the function code. It has a decimal value of 23. 

io socket specifies the socket number. This field is set to 0. 
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io__flags defines specific flag options. You must set this data member to 0. It is 

not used with the synchronous form of the SELECT call. 

For Asynchronous Mode: You can set this data member to 

MSG ASYNC and MSG CALLBACK. MSG ASYNC processes the 

asynchronous I/O form of the SELECT function call. 

MSG CALLBACK allows the network to issue a callback routine 

when the SELECT call completes. 

to psize specifies the size of the data structure select dn as 16 bytes. 

select dn specifies the select data structure which is used for examining bit 

masks. The user fills in data for each field. (See Appendix B on how 
select __dn is formatted.) 

The structure contains the following data fields: 

sel nfds specifies the highest socket number to be checked. The bits 

from (K<0)to(l<< (nfds-1)) are examined. 

sel read specifies the socket numbers (as bit masks) to be examined 

for read ready. For listening sockets, a read ready condition 
indicates that an incoming connection request can be read 
and either accepted or rejected. For sequenced sockets, there 
is a complete message to be read. For stream sockets, there is 
some data to be read. If a socket disconnects or aborts, a read 
ready condition will always occur. 

This descriptor can be given as a zero value if of no interest. 

sel write specifies the socket numbers (as bit masks) to be examined 

for write ready. A write ready condition exists when the logi- 
cal link is available. This descriptor can be given as a zero 
value if of no interest. 

sel except specifies the socket numbers (as bit masks) to be examined 

for out-of-band data ready. There is a pending out-of-band 
data message to receive. This descriptor can be given as a 
zero value if of no interest. 



sel seconds defines the maximum interval to wait for a descriptor selec- 

tion to be completed. If the time value is set to -1, the 
SELECT call will wait until an event occurs. If the time value 
equals 0, then the SELECT call will return after an immediate 
poll. If the time value is greater than zero, the SELECT call 
will return either after n seconds have expired, or when an 
event occurs, whichever one comes first. 
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io callback For Asynchronous Mode: If the MSG CALLBACK bit is set 

in io__flags, then io callback specifies the 4 byte address of 

the function to be called by the network process when the 
function completes. (See Appendix B on how the data type 
exptr is formatted.) 

Output Data 

sel read If a socket is read ready, the bit is returned "on", and sel read 

returns the socket numbers (as bit masks) to be examined. If the socket 
is not read ready, the bit is cleared. 

sel write If a socket is write ready, the bit is returned "on", and sel write 

returns the socket numbers (as bit masks) to be examined. If the socket 
is not write ready, the bit is cleared. 

sel except If the socket is out-of-band data ready, the bit is returned "on", and 

sel except returns the socket numbers (as bit masks) to be examined. 

If the socket is not out-of-band data ready, the bit is cleared. 

For Asynchronous Mode: The number of sockets to be examined for 
read ready, write ready or out-of-band data ready, are not returned 

until to status has changed from a pending condition (-2) and the 

call has successfully completed. 

to status returns the number of descriptors to be examined upon successful 

completion. If an error occurs, to status returns a -1 . io errno will 

also contain additional error detail. 

For Asynchronous Mode: If the call's status is still pending, a value of 

-2 is returned, io status will return the number of descriptors upon 

successful completion. If an error occurs, io status will return a -1. 

io errno will also contain additional error detail. 

io errno returns additional error detail if io status returns a - 1 . (See the DIAG- 

NOSTICS section for a possible error condition.) 

Data Structure Type Summary 

sel ndfs 2 bytes 

sel read 4 bytes 

sel write 4 bytes 

sel except 4 bytes 

sel seconds 2 bytes 

DIAGNOSTICS 



[EBADF] 



One of the specified bit masks is an invalid descriptor. 
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6.7.15 SEND 
NAME 

SEND - send data on a specified socket. 
IOCB Data Members 



Bytes 

+ + 
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Data Fields: Input or Output 

< + 

io fcode: SEND (9) j 

| 

io socket : socket number j 

j j 

v I 

io flags: NEOM | 

j NBOM j 

V ! 

i 

io status : 0, if successful \ 

| -1 if unsuccessful j 

v I 

i 

io errno: error detail, \ 
I if status: -1 | 

v ! 

i 

io psize: user defined < + 

| size of io buffer (input) 

V number of bytes sent (output) 

< + 

i 
i 

Data structure: io buffer | 
< + 



IOCB 
HEADER 
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CIOCB Data Members - For Asynchronous Mode 



Bytes 
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Data Fields: Input or Output 

< 

iofcode: SEND (9) 

io socket: socket number 

i 

V 

io flags : (asynchronous) 

| (callback) 

V (NEOM), (NBOM) 

io status : if successful 
| -1 if unsuccessful 

V -2 for pending status 



io errno: error detail, 
| if status: -1 

V 



io psize: user defined < 

| size of io buffer (input) 

V number of bytes sent (output) 



Data structure: io buffer 



< + 

< + 

offset I 



v 



io callback 



segment 
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DESCRIPTION 

The SEND call is used to transmit data to your peer. The client task uses the socket num- 
ber returned by the ATTACH call. The server task uses the socket number returned by 
the ACCEPT call. 

If you can't get enough buffer space on a blocking socket, the call is blocked. You must 
wait until current transmissions are finished. If the socket is set to nonblocking, the call 

returns with -1 in to status, and the error value EWOULDBLOCK in to errno. If a 

socket disconnects, any outstanding data to be sent is discarded. 

For sequenced sockets, you can send a multi-part message as if it is a single message. To 
do this, you should flag the SEND call with the required message options, NEOM (not 
end of message) and NBOM (not beginning of message). 

NOTE 

NEOM and NBOM are not valid options for stream sockets. Stream 
mode destroys all record boundaries. 

The following example describes how to send a 3-part message and have the SEND call 
treat it as one message. The io_flags are set as follows: 

• first buffer {io_flags = NEOM) 

• second buffer (io_flags = NEOM and NBOM) 

• third buffer (io_flags = NBOM) 

At the receive end, the three-part message would be reconstructed and treated as a sin- 
gle message. 

DESCRIPTION - For Asynchronous Mode 

The SEND call is used to transmit data to your peer. The client task uses the socket num- 
ber returned by the ATTACH call. The server task uses the socket number returned by 
the ACCEPT call. 

When the asynchronous form of the SEND call is used, it is possible that the call may 
not complete. If this occurs, there are two ways for you to check the status of the call: 

• If the asynchronous form of the SEND call is used, you can also specify that a call- 
back routine be used. The message option, MSG CALLBACK, allows the network 

to issue a callback routine when the SEND call completes. 

• If there is no callback routine, you can poll for status. To do this, examine the 

to status field. A value of -2, or -1 may be returned. A value of -2 indicates 

pending (no change) status. If a value of is returned, and the SEND call has com- 
pleted, the number of bytes transferred to your peer is returned in to psize. 

If the call is unsuccessful, to status returns a value of -1. Additional error detail 

will also be contained in to errno. For a description of these error messages, see 

the DIAGNOSTICS section. 
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For sequenced sockets, you can send a multi-part message as if it is a single message. To 
do this, you should flag the SEND call with the required message options, NEOM (not 
end of message) and NBOM (not beginning of message). 

NOTE 

NEOM and NBOM are not valid options for stream sockets. Stream 
mode destroys all record boundaries. 

The following example describes how to send a 3 -part message and have the SEND call 
treat it as one message. The io_flags are set as follows: 

• first buffer (io_flags = NEOM) 

• second buffer (io_flags = NEOM and NBOM) 

• third buffer (io_flags = NBOM) 

At the receive end, the three-part message would be reconstructed and treated as a sin- 
gle message. 



Input Data 

io_fcode 
io socket 

io_J7ags 



io psize 

io buffer 



specifies SEND as the function code. It has a decimal value of 9. 

specifies the number for a socket created by the ACCEPT or the CON- 
NECT call. 

defines specific bit options. For sequenced sockets, you can send a 
multi-part message as if is was a single message. To do this, the SEND 

call is flagged with the message options, MSG NEOM and 

MSG NBOM. When the message is received, it would be recon- 
structed and treated as a single message. 

The hexadecimal value for each option is listed in Appendix A. 

For Asynchronous Mode: You can set io_flags to one or more of the 

following bits: MSG ASYNC processes the asynchronous I/O form of 

the SEND function call. MSG CALLBACK allows the network to 

issue a callback routine when the SEND call completes. For sequenced 
sockets, you can send a multi-part message as if is was a single mes- 
sage. To do this, the SEND call is flagged with the message options, 

MSG NEOM and MSG NBOM. When the message is received, it 

would be reconstructed and treated as a single message. 

The hexadecimal value for each option is listed in Appendix A. 

specifies the size of the user defined buffer. 

specifies the address of the buffer which contains the outgoing mes- 
sage. (Refer to Appendix B on how io buffer is formatted.) 
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io_callback 



Output Data 

to psize 

to status 



to errno 



For Asynchronous Mode: If the MSG CALLBA CK bit is set in 

io___flags, then to callback specifies the 4 byte address of the func- 
tion to be called by the network process when the function com- 
pletes. (See Appendix B on how the data type exptr is formatted.) 



specifies the number of transferred bytes upon successful completion. 

Upon successful completion, a value of is returned. The number of 

bytes transferred to your peer is returned in to psize. If an error 

occurs, to status returns a -1 . to errno will also contain additional 

error detail. 

For Asynchronous Mode: If the call's status is still pending, a value of 
-2 is returned. Upon successful completion, a value of is returned. 

The number of bytes transferred to your peer is returned in to psize. 

If an error occurs, io status returns a -1 . to errno will also contain 

additional error detail. 

returns additional error detail if io status returns a - 1 . (See the DIAG- 
NOSTICS section for a list of error conditions.) 



Data Structure Type Summary 

io buffer 4 bytes 

DIAGNOSTICS 

When sending normal data, the following set of error messages can occur: 
Blocking I/O 

Description 



Message 

[EBADF] 

[EMSGSIZE] 

[ENOTCONN] 

[EPIPE] 

Nonblocking I/O 
Message 

[EBADF] 



The argument io socket does not contain a valid socket num- 
ber. 

The size of the outgoing message is more than 2048 bytes. 

The SEND call did not complete and the link was disconnected. 

The link has been disconnected, aborted or shutdown. No fur- 
ther messages can be sent. 



Description 

The argument io socket does not contain a valid socket num- 
ber. 



[EMSGSIZE] 



The size of the outgoing message is more than 2048 bytes. 
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Message Description 

[ENOTCONN] The SEND call did not complete and the link was disconnected. 

[EPIPE] The link has been disconnected, aborted or shutdown. No fur- 

ther messages can be sent. 

[EWOULDBLOCK] The outbound quota was full, and the message could not be 
sent. 

EWOULDBLOCK is not a valid error message for the asynchro- 
nous form of the SEND call. 
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6.7.16 SENDOOB 
NAME 

SENDOOB - send out-of-band messages on a specified socket. 
IOCB Data Members 



Bytes 

+ + 

I i 

+ + 

! lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi j 

+ + 

! lo I 

+ + 

I hi | 

+ + 

I lo | 
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I hi | 
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I hi j 
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+ + 
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+ + 



Data Fields: Input or Output 

< + 

iofcode: SENDOOB (14) | 

i 

io socket : socket number \ 

\ i 

V I 

i 

io flags: (not used) | 

v I 

io status: if successful, | 

| -1 if unsuccessful j 

v ! 

i 

io errno: error detail, j 

! if status: -1 i 

v ! 

io psize: user defined < + 

| size of io buffer (input) 

V number of bytes sent (output) 

< + 

! 
I 

Data structure: io buffer \ 

i 
i 

< - + 



IOCB 
HEADER 



IOCB 
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LIST 



6-68 



DECnet-DOS Programmer's Reference Manual 



CIOCB Data Members - For Asynchronous Mode 



Bytes 
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Data Fields: Input or Output 

< 

io^fcode: SENDOOB (14) 

io socket: socket number 

V 

io flags : 
V 



( asynchronous ) 
( callback )' 



io status: if successful, 
| -1 if unsuccessful, 

V -2 for pending status 



io errno: error detail, 
| if status: -1 

V 



io psize: user defined < 

| size of io buffer (input) 

V number of bytes sent (output) 



Data structure: io buffer | 

< + 

< + 

offset I 

I 

v 

segment 

I 

v 



io callback 



CIOCB 
HEADER 



CIOCB 
PARAMETER 
LIST 



CALLBACK 
ADDRESS 
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DESCRIPTION 

The SENDOOB call is used to send out-of-band data to your peer. An out-of-band mes- 
sage is a high priority message that you can send to your peer. Out-of-band messages 
are sent to a receiving task ahead of normal messages. If a socket disconnects, any out- 
standing data to be sent is lost. 

DESCRIPTION - For Asynchronous Mode 

The SENDOOB call is used to send out-of-band data to your peer. An out-of-band mes- 
sage is a high priority message that you can send to your peer. Out-of-band messages 
are sent to a receiving task ahead of normal messages. If a socket disconnects, any out- 
standing data to be sent is lost. 

For the asynchronous form of the SENDOOB call, you can only have 1 active out-of- 
band message and 1 pending out-of-band message. 

When the asynchronous form of the SENDOOB call is used, it is possible that the call 
may not complete. If this occurs, there are two ways for you to check the status of the 
call: 

• If the asynchronous form of the SENDOOB call is used, you can also specify that a 
callback routine be used. The message option, MSG CALLBACK, allows the net- 
work to issue a callback routine when the SENDOOB call completes. 

• If there is no callback routine, you can poll for status. To do this, examine the 

io status field. A value of -2, or -1 may be returned. A value of -2 indicates 

pending (no change) status. If a value of is returned, and the SEND call has com- 
pleted, the number of bytes transferred to your peer is returned in io psize. 

If the call is unsuccessful, to status returns a value of -1. Additional error detail 

will also be contained in io errno. For a description of these error messages, see 

the DIAGNOSTICS section. 

Input Data 

io_fcode specifies SENDOOB as the function code. It has a decimal value of 14. 

io socket specifies the number for a socket created by the ACCEPT or CON- 
NECT call. 

io_flags defines specific bit options. You must set this data member to 0. It is 

not used with the synchronous form of the SENDOOB call. 

For Asynchronous Mode: You can set io_flags to MSG ASYNC 

and MSG CALLBACK. MSG ASYNC processes the asynchronous 

I/O form of the SENDOOB function call. MSG CALLBACK allows the 

network to issue a callback routine when the SENDOOB call com- 
pletes. 

The hexadecimal value of each flag option is listed in Appendix A. 
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to psize 

to buffer 

to callback 



Output Data 

to psize 

to status 



to errno 



specifies the size of the user defined buffer. 

specifies the address of the buffer which contains the outgoing out-of- 
band message. (Refer to Appendix B on how to buffer is formatted.) 

For Asynchronous Mode: If the MSG^CALLBACK bit is set in 
to_flags, then to callback specifies the 4 byte address of the func- 
tion to be called by the network process when the function com- 
pletes. (See Appendix B on how the data type exptr is formatted.) 



specifies the number of transferred bytes upon successful completion. 

Upon successful completion, a value of is returned. The number of 

bytes transferred to your peer is returned in to psize. If an error 

occurs, to status returns a -1 . to errno will also contain additional 

error detail. 

For Asynchronous Mode: If the call's status is still pending, a value of 
-2 is returned. Upon successful completion, a value of is returned. 

The number of bytes transferred to your peer is returned in to psize. 

If an error occurs, to status returns a - 1 . to errno will also contain 

additional error detail. 

returns additional error detail if to status returns a - 1 . (See the DIAG- 
NOSTICS section for a list of error conditions.) 



Data Structure Type Summary 

to buffer 4 bytes 

to callback 4 bytes 

DIAGNOSTICS 

When sending out-of-band data, the following set of error messages can occur: 
Blocking I/O 

Description 



Message 

[EALREADY] 

[EBADF] 

[EMSGSIZE] 

[ENOTCONN] 

[EPIPE] 



The out-of-band message could not be sent. A similar transmis- 
sion request is still in progress. 

The argument io socket does not contain a valid socket num- 
ber. 

The size of the outgoing message is more than 16 bytes. 

The SEND call did not complete and the link was disconnected. 

The link has been disconnected, aborted or shutdown. No fur- 
ther messages can be sent. 
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Nonblocking I/O 
Message 

[EALREADY] 

[EBADF] 

[EMSGSIZE] 

[ENOTCONN] 

[EPIPE] 



Description 

The out-of-band message could not be sent. A similar transmis- 
sion request is still in progress. 

The argument io socket does not contain a valid socket num- 
ber. 

The size of the outgoing message is more than 16 bytes. 

The SEND call did not complete and the link was disconnected. 

The link has been disconnected, aborted or shutdown. No fur- 
ther messages can be sent. 
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6.7.17 SETSOCKOPT and GETSOCKOPT 
NAME 

SETSOCKOPT and GETSOCKOPT - set and get the options associated with sockets. 
IOCB Data Members 



Bytes Data Fields: Input or Output 

+ + < + 

| | io_fcode: SETSOCKOPT (25) | 

+ + | 

| lo | io socket: socket number | 

+ + | | 

| hi | V | 

+ + | 

| lo | io flags : (not used) | 

+ + j | 

| hi | V | IOCB 

+ + | HEADER 

| lo | io status: for success, | 

+ + | or -1 if unsuccessful | 

I hi | V | 

+ + | 

| lo | io errno: error detail, | 

+ + | if status: -1 | 

I hi | V ! 

+ + | 

| lo ! io psize : 8 bytes < + 

+ + | 

I hi | V 

+ + 

I I < + 



| | I IOCB 

Data structure: sockopt dn | PARAMETER 

I LIST 

i 

| | < + 

+ + 
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IOCB Data Members 



Bytes 

+ + 

+ + 

I lo | 

+ + 

I hi I 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

! hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 
+ + 

+ + 

I I 

I " I 
+ + 



Data Fields: Input or Output 

< 

io_fcode: GETSOCKOPT (26) 

io socket : socket number 

V 

io flags: (not used) 
V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno: error detail, 
| if status: -1 

V 



iopsize: 8 bytes < 
V 

< 



IOCB 
HEADER 



Data structure: sockopt dn 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The SETSOCKOPT and GETSOCKOPT calls manipulate various options associated 
with a socket. Options exist at multiple levels and you must specify the level number 
for the desired operation. 

NOTE 

In the following discussion, references are made to symbolic values. 
See Appendix A for details. 

At the socket level (SOL SOCKET), the options include: 

• SO KEEP ALIVE. If this option is set on a socket, any links and sockets associated 

with this socket will remain active, despite any attempts to disconnect them. 

NOTE 

Before you can terminate a connection over a socket with the 
option SO_KEEPALIVE set, you must first issue a SETSOCKOPT 
call with SO_KEEPALIVE turned off. 

You then issue either the ABORT, DETACH or DISCONNECT call. 
The logical links (if any) are disconnected, and the socket and asso- 
ciated sockets (if any) are aborted or only disconnected. However, 

if you issue either call without turning off SO KEEP ALIVE, the 

socket remains attached, and the links (if any) stay active. 

• SO LINGER. SO LINGER controls the actions taken when unsent messages are 

queued on a socket and a DISCONNECT call is issued. If SO LINGER is set, the 

connection is maintained until the outstanding messages have been sent. This is the 
default condition. 

• SO DONTLINGER. SO DONTLINGER also controls the actions of unsent mes- 
sages. If SO DONTLINGER is set, and the DISCONNECT call is issued, any out- 
standing messages queued to be sent will be lost. The connection is then termi- 
nated. 

• SO REUSEADDR. SO REUSEADDR allows the reuse of a name already bound 

to a socket. For most situations, a name is bound to a socket only once. However, 
this option enables you to reuse the same name. This particular option must only 
be used for outgoing connection requests. It cannot be used for incoming connec- 
tions. 

VAX/VMS proxy access by user name is made possible if the client task uses the 
BIND call specifying his user name as the object name. If you wish to make more 
than one proxy connection with the same user name, you must use the 
SO REUSEADDR option. 
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At the DECnet level (DNPROTO NSP), socket options may specify the way in which a 

connection request is accepted/rejected, may be used to set up optional user data and/ 
or access control information, may be used to obtain current link state information. 
The following socket options can be specified: 

• DSO ACCEPTMODE. The accept option mode is used at the DECnet level for pro- 
cessing ACCEPT calls. A socket must be bound (See BIND, Section 6.7.4) before 
specifying this option. There are two values which can be supplied for this option. 
They are immediate mode, ACC IMMED, and deferred mode, ACC DEFER. 

- ACC IMMED. ACC IMMED mode is the default condition for this option. 

When immediate mode is in effect, control is immediately returned to the 
server task following an ACCEPT call with the connection request accepted. 
The access control information and/or optional user data is ignored by the 
server task. 

- ACC DEFER. ACC DEFER mode indicates that the server task completes 

the ACCEPT call without fully completing the connection to the client task. In 
this case, the server task can examine the optional access control or user data 
before it decides to accept or reject the connection request. The server task can 
then issue the SETSOCKOPT call with the appropriate reject or accept option. 

• DSO_CONACCEPT. DSO_CONACCEPT allows the server task to accept the 
pending connection on the socket returned by the ACCEPT call. The original listen- 
ing socket was set to deferred accept mode. Any optional user data previously set 
by DSO CONDATA will also be sent. 

• DSO_CONREJECT. DSO_CONREJECT allows the server task to reject the pend- 
ing connection on the socket returned by the A CCEPT call. The original listening 
socket was set to deferred accept mode. Any optional user data previously set by 

DSO DISDATA will also be sent. The reject reason is the value passed with this 

option. 

• DSO_COND ATA. DSO CONDATA allows up to 1 6 bytes of optional user data to 

be set by the SETSOCKOPT call. It can be sent as a result of the CONNECT or the 
A CCEPT (with the deferred option) calls. The optional data is passed in a structure 

of type optdata_dn. (See Appendix B on how optdata dn is formatted.) The 

data is read by the task issuing the GETSOCKOPT call with this option. 

• DSO DISDATA. DSO DISDATA allows up to 16 bytes of optional data to be set 

by the SETSOCKOPT call. It can be sent as a result of the DISCONNECT call. The 
optional data is passed in a structure of type optdata_dn. (See Appendix B on how 
optdata__dn is formatted.) The data is read by the task issuing the GETSOCKOPT 
call with this option. 

• DSO_CONACCESS. DSO_CONACCESS allows access control information to be 
passed by the user task. This information is set with the SETSOCKOPT call. The 
access data is sent to the server task. It is passed with the CONNECT call in a struc- 
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ture of type accessdata dn. (See Appendix B on how accessdata_jdn is format- 
ted.) The access data is read by the task issuing the GETSOCKOPT call with this 
option. 

DSO_LINKINFO. DSO_LINKINFO determines the state of the logical link con- 
nection. 

When GETSOCKOPT call is issued with this option, the state of the logical link is 
returned in a logical link information data structure, linkinfo_dn. (See Appendix 
B on how linkinfo_jdn is formatted.) 



Input Data 

io_fcode 

io socket 

io__flags 

io__psize 
sockopt__dn 

sop level 



specifies SETSOCKOPT&s the function code. It has a decimal value of 
25. This data member also specifies GETSOCKOPT as the function 
code. It has a decimal value of 26. 

specifies the number for a socket created by the ACCEPT and/or 
deferred-mode ACCEPT, or A TTACH call. 

defines specific flag options. You must set this data member to 0. It is 
not used with the SETSOCKOPT or the GETSOCKOPT call. 

specifies the size of the data structure sockopt dn as 8 bytes. 

specifies the socket option data structure. (See Appendix B on how 
sockopt dn is formatted.) 

The structure contains the following data fields: 

specifies the level at which options are manipulated. 

If the level is set to SOL SOCKET, then sop optval and 

sop_optlen are ignored. If the level is set to 
DNPROTO NSP, then the rest of the data structure can con- 
tain either access control or optional user data; or access 
mode information. 



sop__optname 



sop optval, 

sop_joptlen 



specifies options to be interpreted. 

When the socket level is set to DNPROTO_NSP, 
sop_optname can be set to one of 6 specific options. For 

example, DSO CONDATA. (See Appendix A for a list of the 

specific options.) 

specify access option values used with the SETSOCKOPT and 
the GETSOCKOPT calls. The interpretation of each argument 
is function dependent as shown here.- 
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SETSOCKOPT call 

sop_optval specifies the pointer to a buffer which contains information 

for setting access option values. 

sop optlen specifies the size of the option value buffer. 

GETSOCKOPT call 

sop optval specifies the pointer to a buffer which will contain the 

returned value for the requested option(s). 

sop optlen is a value result parameter. It should initially contain the size 

of the buffer pointed to by sop__optval. On return, it will 
contain the actual size of the returned value. 

Output Data 

to status returns a upon successful completion. If an error occurs, to status 

returns a -1. io errno will also contain additional error detail. 

io errno returns additional error detail if io status returns a - 1 . (See the DIAG- 

NOSTICS section for a list of error conditions.) 

GETSOCKOPT call 

sop_optval specifies the pointer to a buffer which contains the returned value for 
the requested socket option(s). 

sop_optlen is a value result parameter. On return, it contains the actual size of the 
returned value for the buffer pointed to by sop optval. 

Data Structure Type Summary 

sop level 2 bytes 

sop__optname 2 bytes 

sop optval 4 bytes 

op optlen 4 bytes 

snd how 2 bytes 
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DIAGNOSTICS 

[EACCES] 
[EBADF] 

[ECONNABORTED] 

[EDOM] 
[ENOBUFS] 

[ENOPROTOOPT] 

[EOPNOTSUPP] 



Unable to disconnect the socket. 

The argument io socket does not contain a valid socket 

number. 

The accept connect did not complete. The peer task dis- 
connected and the connection was aborted. 

The acceptance mode is not valid. 

There are no available buffers for optional access control 
and/or user data. 

There was no access control information supplied with the 
connection request. 

The option is unknown. 
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6.7.18 SHUTDOWN 
NAME 

SHUTDOWN - shut down all or part of a full duplex logical link. 
IOCB Data Members 



Bytes 

+ + 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

| hi | 
+ + 

+ + 

I * I 
+ + 



Data Fields: Input or Output 

< 

io^fcode: SHUTDOWN (7) 

io socket : socket to be 
j shut down 

V 

io flags: (not used) 

I 

V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno: error detail, 
| if status: -1 

V 

io psize: 2 bytes < 

i 

V 

< 

Data structure: shutdown dn 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The SHUTDOWN call causes all or part of a full duplex connection on the original 
socket to be shut down. 



Input Data 

io_fcode 

io socket 

io_Jlags 

io psize 



specifies SHUTDOWN as the function code. It has a decimal value 
of 7. 

specifies the socket number. 

defines specific flag options. You must set this data member to 0. It is 
not used with the SHUTDOWN call. 

specifies the size of the data structure shutdown_dn as 2 bytes. 



shutdown__dn specifies the type of shutdown. (See Appendix B on how 
shutdown dn is formatted.) 



snd how 



Output Data 

io status 

io errno 

DIAGNOSTICS 

[EBADF] 
[ENOTCONN] 



The structure contains the following data field: 

specifies the type of shutdown. This argument can be set to: 

which disallows further receives. 

1 which disallows further sends. 

2 which disallows further sends and receives. 



returns a upon successful completion. If an error occurs, io status 

returns a -1. io errno will also contain additional error detail. 

returns additional error detail if io status returns a - 1 . (See the DIAG- 
NOSTICS section for a list of error conditions.) 



The argument io socket does not contain a valid descriptor. 

The specified socket is not connected. 
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6.7.19 SIOCTL 
NAME 

SIOCTL - control the operations of open sockets. 
IOCB Data Members 



Bytes 

+ + 

+ + 

I lo | 
+ + 

I hi I 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

I lo | 

+ + 

I hi | 

+ + 

| | 

+ + 

I I 

I ' I 
+ + 



Data Fields: Input or Output 

< 

iofcode: SIOCTL (24) 

io socket : socket number 

V 

io flags: (not used) 
V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno: error detail, 
| if status: -1 

V 

io psize: 8 bytes < 

V 

< 

Data structure: sioctl dn 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The SIOCTL call controls the operations of open sockets. The call indicates whether an 
argument is an input or output argument and the size of the specific argument in bytes. 



Input Data 

iO-—fcode 

to socket 

io_flags 

io psize 

sioctl dn 



sto 5 

sio request 



argp 



specifies SIOCTL as the function code. It has a decimal value of 24. 
specifies the socket number. 

defines specific flag options. You must set this data member to 0. It is 
not used with the SIOCTL call. 

specifies the size of the data structure sioctl_dn as 8 bytes. 

specifies the socket I/O control function data structure. (See Appendix 
B on how sioctl_dn is formatted.) 

The structure contains the following data fields: 

This data field is ignored. 

specifies the I/O control function to be used. The control 
levels include: 

FIONREAD returns the total byte count of all messages wait- 
ing to be read, argp points to a word. 

FIONBIO sets/clears blocking or nonblocking I/O operation. 
argp points to a byte that contains a value of or 1 . For block- 
ing I/O, argp should point to a value of 0. For nonblocking 
I/O, argp should point to a value of 1 . 

FIORENUM renumbers an assigned socket number to another 
number. In this way, the original socket number is made avail- 
able again. The valid range for socket numbers is to 31. 
argp points to a word. 

The SELECT function call cannot accept socket numbers that 
exceed this range. (See Section 6.7.14 for details.) 

If you specify a socket number that is already in use, an error 
message, EEXIST, is returned. 

specifies the address of the argument list. 
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Output Data 

to status returns a upon successful completion. When the call is successful, 

argp (only if it is FIONREAD) returns the total byte count of all mes- 
sages waiting to be read. 

If an error occurs, to status returns a -1 . to errno will also contain 

additional error detail. 

to errno returns additional error detail if to status returns a - 1 . (See the DIAG- 
NOSTICS section for a list of error conditions.) 

Data Structure Type Summary 

sio s 2 bytes 

sio request 2 bytes 

argp 4 bytes 

DIAGNOSTICS 

[EBADF] The argument to socket does not contain a valid socket num- 

ber. 

[EOPNOTSUPP] The socket type does not support the socket I/O operation. 
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6.7.20 SOCKADDR 
NAME 

SOCKADDR - retrieve socket information set by the BIND call. 
IOCB Data Members 



Bytes 



Data Fields: Input or Output 



lo 



hi 



lo 



hi 



lo 



hi 



lo 



hi 



lo 



hi 



+ < 

! iofcode: SOCKADDR (15) 



io socket: socket number 
V 

io flags: (not used) 
V 

io status: for success, 

| or -1 if unsuccessful 

V 

io errno: error detail, 
| if status: -1 

V 

io psize: 26 bytes < 

V 

< 

Data structure: sockaddr dn 



IOCB 
HEADER 



IOCB 
PARAMETER 
LIST 
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DESCRIPTION 



The SOCKADDR call returns socket information set by the BIND call. If no BIND call 
was ever executed, undefined results are returned in output data fields. 

Input Data 

io_fcode specifies SOCKADDR as the function code. It has a decimal value of 

15. 

io socket specifies the number for a socket which was bound to a name by the 

BIND call. 

io_flags defines specific flag options. You must set this data member to 0. It is 

not used with the SOCKADDR call. 

io psize specifies the size of the data structure sockaddr_dn as 26 bytes. 

Output Data 

io status returns a upon successful completion. If an error occurs, io status 

returns a -1 . io errno will also contain additional error detail. 

io errno returns additional error detail if io status returns a - 1 . (See the DIAG- 

NOSTICS section for a list of error conditions.) 

sockaddr_dn specifies the socket address data structure. A user retrieves data from 
the fields filled in by this function call. (See Appendix B on how 
sockaddr_dn is formatted.) 



sdn_family 
sdn objnum 

sdn objnamel 

sdn_objname 

sdn add 



The following data fields can be filled in by this function call: 
is the address family AF DECnet. 



is the object number for the local task. It can be a number to 
255. 

is the size of the object name. 

is the object name of the local task. It can be up to a 16-byte 
array. It is only used when sdn objnum equals 0. 

specifies the address structure for the local node. (See Appen- 
dix B on how sockaddr_dn is formatted.) 
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Data Structure Type Summary 

sdn_family 2 bytes 

sdn__flags 1 byte 

sdn_objnum 1 byte 

sdn objnamel 2 bytes 

sdn_objname 16-byte array 

sdn_add 4 bytes 

DIAGNOSTICS 

[EBADF] The argument io socket does not contain a valid socket number. 
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Socket Definitions 



The following definitions are related to socket types, option flags and other related 
socket definitions. The symbols that appear in this appendix are defined in the DECnet 
header files. 

A.1 Communications Domain 

DECnet-DOS supports the following communications domain: 
Decimal 

Value Domain Description 

1 AF DECnet Enables multiple computer systems to participate in com- 

munications and resource sharing within a DECnet net- 
work. 

The symbol is defined in < socket. h > header file. 

A.2 DECnet Layers 

The following DECnet layers are supported by DECnet-DOS: 
Hexadecimal/ 

Decimal Value Layer Description 

Oxffff SOL SOCKET Specifies the socket session interface layer. 

1 DNPROTO_NSP Specifies the DECnet layer. How a connection 

request is accepted/rejected, optional access con- 
trol and/or user data, or link state can be specified. 
(See Appendix B for a list of defined data struc- 
tures.) 

These symbols are defined in < socket. h> header 
file. 
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A.3 DECnet Objects 

Certain DECnet object numbers are used as arguments to the dnet conn call. The fol- 
lowing are ASCII strings: 



Object 

DNOBJ FAL 

DNOBJ_NICE 

DNOBJ TERM 

DNOBJ MIRROR 

DNOBJ EVR 

DNOBJ_MAILll 

DNOBJ PHONE 

DNOBJ CTERM 

DNOBJ DTR 



ASCII String 

#17 (File Access Listener) 

#19 (Network Information and Control Exchange) 

#23 (Network command terminal handler - host side) 

#25 (Loopback mirror - MIR) 

#26 (Event receiver - EVR) 

#27 (Personal message utility) 

#29 (Phone utility) 

#42 (Command terminal operations) 

#63 (DECnet test receiver tool - DTR) 



The following are decimal numbers: 



Decimal 
Value 

17 

19 

23 

25 
26 
27 
29 
42 
63 



Object 

DNOBJECT FAL 

DNOBJECT NICE 

DNOBJECT DTERM 

DNOBJECT__MIRROR 

DNOBJECT EVR 

DNOBJECT MAIL 1 1 

DNOBJECT PHONE 

DNOBJECT CTERM 

DNOBJECT DTR 



Process Type 

File Access Listener 

Network Information and Control 
Exchange 

Network command terminal handler - 
host side 

Loopback mirror (MIR) 
Event receiver (EVR) 
Personal message utility 
Phone utility 

Command terminal operations 
DECnet test receiver tool (DTR) 



These symbols are defined in <dn.h> header file. 
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A.4 DECnet Options 



At the DECnet layer (DNPROTO NSP), socket options can define how a connection 

request is accepted/rejected, specify optional user data and/or access control informa- 
tion, or obtain current link state information. The following options can be used to 
specify or retrieve data with the setsockopt and getsockopt function calls: 



Decimal 
Value 



Option 

DSO CONDATA 



DSO DISDATA 



DSO_CONACCESS 



DSO__ACCEPTMODE 



ACC IMMED 



Description 

Allows up to 16 bytes of optional user 
data to be set by the setsockopt call. The 
optional data is passed in the 
optdata_dn data structure. The user 
task reads the data by issuing the 
getsockopt call with the connect option. 
The call returns a connect status. 

Allows up to 16 bytes of optional user 
data to be set by the setsockopt call. The 
optional data is passed in the 
optdata_dn data structure. The user 
task reads the data by issuing the 
getsockopt call with the disconnect 
option. The call returns a disconnect 
status. 

Allows access control information to be 
set by the setsockopt call. The access con- 
trol information is passed in the 
accessdata_dn data structure. The user 
task reads the data by issuing the 
getsockopt call. The information is pro- 
cessed once the task issues the accept 
call. 

Defines the way in which a user task 
accepts a pending accept call. A socket 
must issue a bind call before this option is 
valid. The acceptance mode can be speci- 
fied as follows: 

Specifies the default condition. The 
accept call is immediately completed. 



(continued on next page) 
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Decimal 



Value Option 

1 ACC DEFER 

5 DSO_CONACCEPT 

6 DSO_CONREJECT 

7 DSO_LINKINFO 

7 DSO_MAX 



Description 

Allows the server task to complete the 
accept call without fully completing the 
connection to the client task. The server 
task can examine the source address, 
access control and/or optional user data 
before accepting or rejecting the pending 
connection. 

Allows the server task to accept the pend- 
ing connection on the socket previously 
set to the deferred accept mode 

(ACC DEFER). Any optional user data 

previously set by DSO CONDATA will 

also be sent. 

Allows the server task to reject the pend- 
ing connection on the socket previously 
set to the deferred accept mode 

(ACC DEFER). Any optional user data 

previously set by DSO DISDATA will 

also be sent. 

Allows the user task to retrieve the state 
of the logical link connection. There are 
four supported link states. (See Section 
A.6) 

The link state is returned in the 
linkinfo_dn data structure. It is 
retrieved with the getsockopt call. 

Specifies the allowable number of 
defined socket options. 

These symbols are defined in <dn.h> 
header file. 
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A.5 Flag Options 



The following bits can be set in the io_flags field which is included in the IOCB and/or 
CIOCB: 



Hexadecimal 

Value Message 



Oxl 



0x2 



0x8 



0x10 



MSG_OOB 



MSG PEEK 



MSG ASYNC 



MSG CALLBACK 



0x20 



MSG NEOM 



0x40 



MSG NBOM 



Description 

Process out-of-band messages with the 
send and recv calls. 

The symbol is defined in < socket. h> 
header file. 

Read the next pending message without 
removing the message from the receive 
queue. The symbol is defined in 
< socket. h > header file. 

Process the asynchronous I/O form of 
DECnet function calls. 

The symbol is defined in < socket. h> 
header file. 

Allows the network to issue a callback 
routine when a specific function call 
completes. 

The symbol is defined in < socket. h> 
header file. 

For sequenced sockets, use MSG NEOM 

with the option MSG NBOM to send a 

multi-part message as if it was a single 
message. To receive a single message in 
multiple parts, flag the receive call with 
MSG NEOM. 

The symbol is defined in < socket. h> 
header file. 

For sequenced sockets, flag the send call 

with MSG NBOM and MSG NEOM to 

send a multi-part message as if it was a 

single message. MSG NBOM cannot be 

used for receive operations. 

The symbol is defined in < socket. h> 
header file. 



Socket Definitions 



A-5 



A.6 Logical Link States 

The following logical link states are supported by DECnet-DOS. 



Decimal 
Value 



1 

2 
3 



State 

LL INACTIVE 

LL CONNECTING 

LL RUNNING 

LL DISCONNECTING 



Description 

The logical link is inactive. 
The logical link is connecting. 
The logical link is running. 
The logical link is disconnecting. 



The symbols are defined in <dn.h> header file. 

A. 7 Maximum Number of Incoming Connection Requests 

The maximum number of incoming connection requests is specified as follows: 



Hexadecimal 
Value 

0x5 



Message 

SOMAXCONN 



Description 

Defines the maximum number of incoming 
connection requests which are allowed on the 
specified socket. 

The symbol is defined in < socket. h> header 
file. 



A.8 Socket Interface Options 

At the socket level (SOL SOCKET), the following options exist: 



Hexadecimal 
Value 

0x04 



0x08 



Flag 

SO REUSEADDR 

SO_KEEPALIVE 



Description 

Allows the reuse of a bound socket name. 
This option must only be used for outgo- 
ing connection requests. 

If this option is set on a socket, any links 
and sockets associated with this socket 
remain active, despite any attempts to 
abort, detach and/or disconnect them. 
The effects of ABORT, DETACH, and 
DISCONNECT functions are only real- 
ized after SO_KEEPALIVE is turned off. 



(continued on next page) 
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Hexadecimal 

Value Flag 



Description 



0x80 SO LINGER 



SO LINGER SO DONTLINGER 



Controls the actions taken when unsent 
messages are queued on a socket and the 
sclose (or the DISCONNECT) call is 
issued. If SO LINGER is set, the connec- 
tion is maintained until the outstanding 
messages have been sent. 

Controls the actions of unsent messages. 

If SO DONTLINGER is set, and the 

sclose (or the DISCONNECT) call is 
issued, any outstanding messages queued 
to be sent will be lost. The connection is 
then terminated. 



The symbols are defined in < socket. h> header file. 



A.9 Socket Types 

DECnet-DOS supports the following socket types: 



Decimal 
Value 



Type 

SOCK STREAM 



SOCK_SEQPACKET 



Description 

Stream sockets cause bytes to accumulate 
until internal DECnet buffers are full. The 
receiving task does not know how many 
bytes were sent in each write operation. 

Sequenced sockets cause bytes to be sent 
immediately. The receiving task receives 
those bytes in one "record". 



The symbols are defined in < socket. h> header file. 
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A.1 Defined Software Modules 

The following software modules are supported by DECnet-DOS. They have defined 



three letter acronym (tla) strings. 






Module 
Name 




TLA 
String 




Description 


DNMOD_ 


_LAT 


LAT 




TAT rlrivfr 
L,I\ 1 HI 1 V CI 


DNMOD PDV 


PDV 




Port driver 


DNMOD_ 


_SCH 


SCH 




Real-time Scheduler 


DNMOD DLL 


DLL 




Data Link Layer 


DNMOD_ 


_DNP 


DNP 




DECnet Network Process 


The following interrupt vectors have been defined for these DECnet-DOS 
modules: 


Vector 

Number 

(Hex) 




Symbol 




Description 


0x6a 




DNMODULE_ 


.LAT 


LAT driver 


0x6b 




DNMODULE_ 


.PDV 


Port Driver 


0x6c 




DNMODULE_ 


.SCH 


Real-time Scheduler 


0x6d 




DNMODULE_ 


.DLL 


Data Link Layer 


0x6e 




DNMODULE_ 


.DNP 


DECnet Network Process 



The symbols are defined in < dn.h > header file. 
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B 

Defined Data Structures and Data Members 



The following data structures can be used with specific socket interface and assembly 
language network driver interface calls. Guidelines for specifying a data structure are 
detailed with the appropriate function call. The symbols that appear in this appendix 
are defined in the DECnet header files. 

If data type exptr is used as an address (or a long pointer), it takes the following format. 
It is defined in < types. h> header file. 



Bytes 



+ + 

I lo | 

+ + offset 

I hi | 
+ + 

I lo | 

+ + segment 

I hi | 
+ + 
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B.1 Access Control Information Data Structure 



The cicc6ssclcitci_ 


dn data structure 


contains the following data members: 


Type 


Size 


Data 
Member 


Description 


unsigned short 


2 bytes 


acc accl 


Defines the length of the account string. 


unsigned char 


40-byte array 


acc acc 


Specifies the account string. 


unsigned short 


2 bytes 


acc passl 


Defines the length of the password string. 


unsigned char 


40-byte array 


acc pass 


Specifies the password string. 


unsigned short 


2 bytes 


acc userl 


Defines the length of the user ID string. 


unsigned char 


40-byte array 


acc user 


Specifies the user ID string. 


The symbols are defined in the < dn.h > header file. 



B.2 Attach Data Structure 

The attach_dn data structure contains the 



Type 

int 



Data 

Size Member 

2 bytes att socket 



unsigned short 2 bytes att_domain 

unsigned short 2 bytes att type 

unsigned short 2 bytes att protocol 

unsigned short 2 bytes att srp 

unsigned short 2 bytes att supreq 



following data members: 
Description 

Specifies the number of the socket. If non- 
zero, the other data structure members are 
ignored. 

Specifies the communications domain for 
the socket as AF DECnet. 

Specifies the socket type for the socket. For 

example, SOCK STREAM . (See Appendix A 

for a list of defined socket types.) 

Specifies the protocol for the socket. For 
example, DNPROTO_NSP. (See Appendix 
A for a list of defined protocol interfaces.) 

Specifies the socket recovery period. 

Specifies the support requirements. 



The symbols are defined in <dnmsdos.h> header file. 



B-2 



DECnet-DOS Programmer's Reference Manual 



B.3 DECnet Node Address Data Structure 



The dn naddr data structure contains the following data members: 



Type 

unsigned 
short 

unsigned 
char 



Size 

2 bytes 

2 -byte 
array 



Data 
Member 

a len 



a addrfDN^MAXADDLJ 



Description 

Specifies the length of the DECnet 
node address. 

Specifies the DECnet Phase IV node 
address for the user task. When 

a addr[DN__MAXADDL] is used as 

a 1 6-bit unsigned integer, bits 0-9 are 
the node number, and bits 10-15 are 
the area number. 



The symbols are defined in < dn.h> header file. 



B.4 Listen Data Structure 

The listen_dn data structure contains the following data member: 
Data 

Type Size Member Description 

int 2 bytes Isn backlog Defines the maximum number of unaccepted incoming 

connects which are allowed on this particular socket. 



The symbol is defined in < dnmsdos.h> header file. 
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B.5 Local Node Information Data Structure 



The localinfo_dn data structure contains the following data members: 



Type 

unsigned 
char 

unsigned 
char 

unsigned 
short 



unsigned 
short 



unsigned 
char 

unsigned 
char 

exptr 



Size 

3-byte 
array 

7-byte 
array 



1 byte 
1 byte 
4 bytes 



Data 
Member 

lei version 



lei nodename 



2 bytes lei nodeaddr 



2 bytes Icl^jsegsize 



lei sockets 



Description 

Specifies the software version number for the 
network process. 

Specifies the node name for the local node. It is 
terminated by a null character. 

Specifies the DECnet Phase IV node address for 
the local node. The node address is formatted 
as a 1 6-bit unsigned integer, where bits 0-9 are 
the node number and bits 10-15 are the area 
number. 

Specifies the minimum buffer segment size used 
on the logical link. This number should match 
the value defined with the NCP command, 
DEFINE EXECUTOR SEGMENT BUFFER SIZE. 
(Refer to the DECnet-DOS User's Guide for 
more details.) 

Specifies the number of sockets available for 
data exchange. 



lcl_decnet_device Specifies the DECnet database device name. 

lcl_decnet_path Specifies the address of a buffer that contains 
the DECnet database path specification string 
which includes the device name. 



The symbols are defined in <dnmsdos.h> header file. 



B.6 Logical Link Information Data Structure 

The linkinfo_dn data structure contains the following data members: 

Data 

Type Size Member Description 

unsigned short 2 bytes idn segsize Specifies the buffer segment size in use on 

the logical link. 

unsigned char 1 byte idn linkstate Specifies the state of the logical link. (See 

Appendix A for a list of logical link states.) 



The symbols are defined in <dn.h> header file. 
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B.7 Optional User Data Structure 

The optdata_dn data structure contains the following data members: 



Type 

unsigned short 

unsigned short 
unsigned char 



Size 

2 bytes 

2 bytes 

16-byte 
array 



Data 
Member 

opt status 



opt_optl 
opt_data 



Description 

Specifies an extended status value returned 
by function call. A list of the extended error 
codes appear in Appendix D. 

Is the size of the optional user data. 

Specifies the optional user data. 



The symbols are defined in < dn.h> header file. 

B.8 Select Data Structure 

The select dn data structure contains the following data members: 



Type 

unsigned short 
field32 
field32 
field32 

unsigned short 



Size 

2 bytes 

4 bytes 
4 bytes 
4 bytes 
2 bytes 



Data 
Member 

sel nfds 



sel_read 



sel write 



sel_except 



sel seconds 



Description 

Specifies the highest socket number to be 
checked. 

Specifies the socket numbers to be examined 
for read ready or incoming connections. 

Specifies the socket numbers to be examined 
for write ready. 

Specifies the socket numbers to be examined 
for exception or out-of-band data ready. 

Specifies the time to wait for the socket selec- 
tion to complete. 



NOTE 

field32 is the same as unsigned long for type. 
The symbols are defined in < dnmsdos.h > header file. 
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B.9 Shutdown Data Structure 

The shutdown_dn data structure contains the following data member: 
Data 

Type Size Member Description 

int 2 bytes snd how Specifies the type of shutdown. The argument can be 

set to: 

which disallows further receives. 

1 which disallows further sends. 

2 which disallows further sends and receives. 

The symbol is defined in < dnmsdos.h > header file. 



B. 1 Socket Address Data Structure 

The sockaddr_dn data structure contains the following data members: 



Type 


Size 


Data 
Member 


Description 


unsigned 
short 


2 bytes 


sdn_ 


.family 


Specifies the communications domain as 
AF DECnet. 


unsigned 
char 


1 byte 


sdn_ 


-flags 


Specifies the object flag option. It must be set to 
zero, if not used. 


unsigned 
char 


1 byte 


sdn_ 


jobjnum 


Defines the object number for the socket. 


unsigned 
short 


2 bytes 


sdn_ 


jobjnamel 


Is the size of the node's object name. 


char 


16-byte 
array 


sdn_ 


jobjname 


Defines the name of the network task. 


struct 


4 bytes 


sdn_ 


jadd 


Specifies the node address data structure. (See the 
description of the dn naddr data structure in this 



appendix.) 

The symbols are defined in < dn.h > header file. 
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B.1 1 Socket I/O Status Data Structure 

The sioctl_dn data structure contains the following data members: 



Type Size 

int 2 bytes 

int 2 bytes 



Data 
Member 

sio s 

sio request 



exptr 



4 bytes argp 



Description 

This data member is not used by the ATTACH call. 

Specifies the I/O control level to be used. (See Section 
4.4.14 for details.) 

Specifies the address of the argument list. 



The symbols are defined in <dnmsdos.h> header file. 

B.1 2 Socket Option Data Structure 

The sockopt_dn data structure contains the following data members: 



Type 

int 



Size 

2 bytes 



Data 
Member 

sop level 



int 



Description 

Specifies the layer at which options are manipu- 
lated. 

If the level is set to SOL_SOCKET, then the rest of 
the data structure is ignored. If the level is set to 

DNPROTO NSP, then the rest of the data structure 

can contain either access control and/or optional 
data; or acceptance mode information. 

2 bytes sop_optname Specifies options to be passed for interpretation. 

When the socket level is set to DNPROTO_NSP, 

sop optname can be set to one of 7 specific 

options. For example, DSO CONDATA. (See 

Appendix A for a list of the specific options.) 



exptr 



4 bytes sop_optval 



exptr 



4 bytes sop_optlen 



Specifies an address for the buffer which contains 
either access control or optional user data. (See Sec- 
tion 4.4.12 for the relationship between 
sop optname and sop_optval arguments.) 

Specifies an address for the buffer which contains 
acceptance mode information. 

Specifies the size of the option value buffer used as a 
parameter for the setsockopt call. 

It is also a value result parameter for the getsockopt 
call. 



The symbols are defined in <dnmsdos.h> header file. 



Defined Data Structures and Data Members 



B-7 



B. 1 3 User Access Control Information Data Structure 



The dnet accent data structure contains the following data members: 



Type 

char 
char 



char 



char 



Size 

1 byte 
1 byte 



40-byte 
array 

40-byte 
array 



Data 
Member 

acc status 

acc type 



accc user 



acc pass 



Description 

Is used internally by this function call. 

Specifies the type of privilege associated with the 
user name or password. The four access types are: 
for no access rights, 1 - read only access, 2 - write 
only access and 3 for read and write access. 

Specifies the user name. It consists of a 1 to 39 alpha- 
betic character string terminated by a null character. 

Specifies the password associated with a user name. 
It consists of a 1 to 39 alphabetic character string ter- 
minated by a null character. 



These symbols are defined in < dnetdb.h> header file. 

B. 1 4 User Defined Callback Routine Data Structure 

The to callback member of the CIOCB has the following format: 

Data 

Type Size Member Description 

exptr 4 bytes io_callback Specifies the address for the callback routine which 

will be returned when a function call completes. 

You should refer to Chapter 6 of this manual for more details on the CIOCB data struc- 
ture. 

B. 1 5 User Defined Data Buffer Structure 

The to buffer member of the lOCB(CIOCB) data structure has the following format: 

Data 

Type Size Member Description 

exptr 4 bytes to buffer Specifies the address for the buffer which contains 

user defined data. 

You should refer to Chapter 6 of this manual for more details on the IOCB and CIOCB 
data structures. 
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c 

Summary of Error Completion Codes 



This appendix lists the error completion codes returned by DECnet-DOS in errno. 
They provide extended error information to transparent file access, transparent task- 
to-task operations, and nontransparent task-to-task communication. 

These error codes are a subset of the error codes contained in the external variable 
errno. The following descriptions are standard ULTRIX definitions. You should refer 
to specific DECnet-DOS calls for a network definition of the error codes. 



Mnemonic 


Decimal 
Value 


Description 


ESRCH 


3 


No such process 


E2BIG 


7 


Argument list too long 


EBADF 


9 


Bad file number 


EACCES 


13 


Permission was denied 


EFAULT 


14 


Bad address 


EBUSY 


16 


Mount device busy 


EEXIST 


17 


File exists 


EINVAL 


22 


Invalid argument 


EMFILE 


24 


Too many open files 


ENOSPC 


28 


No space left on device 


EPIPE 


32 


Broken pipe 



(continued on next page) 
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Decimal 

Mnemonic Value 
Math software 

EDOM 33 

ERANGE 34 
Nonblocking and interrupt I/O 

EWOULDBLOCK 35 

EINPROGRESS 36 

EALREADY 37 
Argument errors 

ENOTSOCK 38 

EDESTADDRREQ 39 

EMSGSI2E 40 

ENOPROTOOPT 42 

EPROTONOSUPPORT 43 

ESOCKTNOSUPPORT 44 

EOPNOTSUPP 45 

EAFNOSUPPORT 47 

EADDRINUSE 48 

EADDNOTAVAIL 49 
Operational errors 

ENETDOWN 50 

ENETUNREACH 51 

ECONNABORTED 53 

ECONNRESET 54 

ENOBUFS 55 

EISCONN 56 

ENOTCONN 57 

ETOOMANYREFS 59 

ETIMEDOUT 60 

ECONNREFUSED 61 



Description 

Argument too large 
Result too large 

Operation would block 
Operation now in progress 
Operation already in progress 

Socket operation on nonsocket 

Destination address required 

Message too long 

Protocol not available 

Protocol not supported 

Socket type not supported 

Operation not supported on socket 

Address family not supported by proto- 
col family 

Address already in use 

Can't assign requested address 

Network is down 
Network is unreachable 
Software caused connection abort 
Connection reset by peer 
No buffer space available 
Socket is already connected 
Socket is not connected 
Too many references: cannot splice 
Connection timed out 
Connection refused 

(continued on next page) 
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Decimal 

Mnemonic Value 

ENAMETOOLONG 63 
EHOSTDOWN 64 
EHOSTUNREACH 65 



Description 

File name too long 
Host is down 
No route to host 
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D 

Summary of Extended Error Codes 



DECnet-DOS supports extended error support to certain socket operations. When you 
write a program which uses the getsockopt function call, extended error codes can be 

returned in opt status, a data member of optdata_dn. This can occur following an 

attempted connection request or after disconnecting a logical link. 

Table D-1 lists extended error codes which can be returned following an attempted 
connection. It lists the error messages found in derrno.h, the decimal value for each 

message, their equivalent error message that dnet conn returns in errno, and the 

error reason. 

Table D-1 : Extended Error Messages - Unable to Make a Connection 



Decimal 
Error Code 



derrno.h 
Mnemonic 

EREJBYOBJ 



EINSSNETRES 



EUNRNODNAM 



EREMNODESHUT 



EUNROBJ 



dnet conn 

In errno 

ECONNREFUSED 



ENOSPC 

EADDRNOTAVAIL 

ENETDOWN 

ESRCH 



Reason 

Connect failed. Connec- 
tions rejected by object. 

Connect failed. Insuffi- 
cient network resources. 

Connect failed. Unrecog- 
nized node name. 

Connect failed. Remote 
node shutting down. 

Connect failed. Invalid 
object name format. 



(continued on next page) 
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Table D-1 (cont.): Extended Error Messages - Unable to Make a Connection 



Decimal 
Error Code 

5 
6 
10 
11 

34 
38 
39 



derrno.h 
Mnemonic 

EINVOBJNAM 



EOBJBUSY 
EINVNODNAM 



EACCONREJ 



ENORESPOBJ 



ENODUNREACH 



dnet conn 

In errno 

EINVAL 



ETOOMANYREFS 



ENAMETOOLONG 



ELOCNODESHUT EHOSTDOWN 



ECONNABORTED 



ETIMEDOUT 



ENETUNREACH 



Reason 

Connect failed. Invalid 
object name format 

Connect failed. Object 
too busy. 

Connect failed. Invalid 
node name format. 

Connect failed. Local 
node shutting down. 

Connect failed. Access 
control rejected. 

Connect failed. No 
response from object. 

Connect failed. Node 
unreachable. 



Table D-2 lists extended error codes which can be returned following a disconnection. 
It lists the error messages found in derrno.h, the decimal value for each message and 
the error reason. 

Table D-2: Extended Error Messages - Disconnecting a Logical Link 



Decimal 
Error Code 



8 

9 



38 



derrno.h 
Mnemonic 

EREJBYOBJ 

EABTBYNMGT 

EUSERABORT 



ENORESPOBJ 



Reason 

The end user disconnected a running logical link. 
The logical link was disconnected by a third party. 
The remote end user has aborted the link. 

Use of this symbol may not be DECnet-ULTRIX com- 
patible. 

A third party has aborted the link, or the node at the 
other end has crashed. 
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E 

Data Access Protocol (DAP) Error Messages 



The Network Task Error log utility provides extended error support to transparent file 
access operations. This appendix lists DAP error messages that can be returned by this 
utility. The Network File Transfer Utility may also return some of these error messages. 

E.1 Overview 

The DAP messages return status from the remote file system or from the operation of 
the cooperating process using DAP. The 2 -byte status field (16 bits) is divided into two 
fields: 

• Maccode (bits 12-15): Contains the error type code (See Table E-1) in Sec- 

tion E. 1.1) 

• Miccode (bits 0-1 1): Contains the specified error reason code (See Tables 

E-2, E-3, and E-4, depending on error type, as 
described in Section E. 1 .2) 

E.1.1 Maccode Field 

The value returned in the maccode field describes the functional type of the error that 
has occurred. The specific reason for the error is given in the miccode field. Miccode 
values correlating to each maccode value listed in Table E- 1 are found in the table ref- 
erenced in the last column of Table E-1 . 
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Table E-1 : DAP Maccode Field Values 



Field 

Value 

(Octal) 

o 

1 

2 



5 
6 

7 

10 

11 



12 

13-15 
16-17 



Miccode 

Error Type Meaning Table 

Pending The operation is in progress. E-3 

Successful Returns information that indicates success. E-3 

Unsupported This implementation of DAP does not support E-2 
the specified request. 

Reserved 

File open Errors that occur before a file is E-3 

successfully opened. 

Transfer Errors that occur after a file is opened and E-3 

error before it is closed. 

Transfer For operations on open files, indicates E-3 

warning that the operation completed, but not with 

complete success. 

Access Errors associated with terminating access E-3 

termination to a file. 

Format Error in parsing a message. Format is not E-2 

correct. 

Invalid Field of message is invalid (that is, bits that E-2 

are meant to be mutually exclusive are set, 
an undefined bit is set, a field value is out of 
range, or an illegal string is in a field.) 

Sync DAP message received out of synchronization. E-4 

Reserved 

User-defined status maccodes 



E.1.2 Miccode Field 

The value returned in this field identifies the specific reason for the error type defined 
in the maccode field (See Section E.l. 1). Miccode field values are defined in three dif- 
ferent tables, each table associated with certain maccode values, as outlined below: 

• Table E-2: For use with maccode values 2, 10, 11 

• Table E-3: For use with maccode values 0, 1,4, 5, 6, 7 

• Table E-4: For use with maccode value 12 
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Table E-2 follows. The DAP message type number (column 1) is specified in bits 6-11, 
and the DAP message field number (column 2) is specified in bits 0-5. The field where 
the error is located is described in the third column. 

Table E-2: DAP Miccode Values for Use with Maccode Values of 2, 1 0, 11 



Type 
Number 
(bits 6-11) 



Field 
Number 
(bits 0-5) 



Miscellaneous message errors 



00 



00 
10 



Configuration message errors 

01 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 
27 

Attributes message errors 



02 



00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 
27 
30 
31 
32 



Field Description 



Unspecified DAP message error 
DAP message type field (TYPE) error 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

BITCNT field (BITCNT) 

Buffer size field (BUFSIZ) 

Operating system type field (OSTYPE) 

File system type field (FILESYS) 

DAP version number (VERNUM) 

ECO version number field (ECONUM) 

USER protocol version number field (USRNUM) 

DEC software release number field (DECVER) 

User software release number field (USRVER) 



Unknown Field 

DAP message flags field (FLAGS) 

Data stream identification (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN 256) 

Bit count field (BITCNT) 

Attributes menu field (ATTMENU) 

Data type field (DATATYPE) 

Field organization field (ORG) 

Record format field (RFM) 

Record attributes field (RAT) 

Block size field (BLS) 

Maximum record size field (MRS) 

Allocation quantity field (ALQ) 

Bucket size field (BKS) 

Fixed control area size field (FSZ) 

Maximum record number field (MRN) 

(continued on next page) 
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Table E-2 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 1 0, 11 



Type 
Number 
(bits 6-11) 



Access message errors 

03 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 

Control message errors 

04 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 
27 
30 



Field 




Number 




(bits 0-5) 


Field Description 


33 


Run-time system field (RUNSYS) 


34 


Default extension quantity field (DEQ) 


35 


File options field (FOP) 


36 


Byte size field 


37 


Device characteristics field (DEV) 


40 


Spooling device characteristics field (SDC); reversed 


41 


Longest record length field (LRL) 


42 


Highest virtual block allocated field (HBK) 


43 


End-of-block field (EBK) 


44 


First free byte field (FFB) 


45 


Starting LBN for contiguous file field (SBN) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit Count field (BITCNT) 

Access function field (ACCFUNC) 

Access options field (ACCOPT) 

File specification field (FILESPEC) 

File access field (FAC) 

File-sharing field (SHR) 

Display attributes request field (DISPLAY) 

File password field (PASSWORD) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Control function field (CTLFUNC) 

Control menu field (CTLMENU) 

Record access field (RAC) 

Key field (KEY) 

Key of reference field (KRF) 

Record options field (ROP) 

Hash code field (HSH); reserved for future use 

Display attributes request field (DISPLAY) 

Block count (BLKCNT) 

(continued on next page) 
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Table E-2 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 1 0, 1 1 



Type Field 

Number Number 

(bits 6-1 1 ) (bits 0-5) Field Description 

Continue message errors 

05 00 Unknown field 

1 DAP message flags field (FLAGS) 

1 1 Data stream identification field (STREAMID) 

1 2 Length field (LENGTH) 

1 3 Length extension field (LEN2 56) 

1 4 Bit count field (BITCNT) 

20 Continue transfer function field (CONFUNC) 

Acknowledge message errors 

06 00 Unknown field 

10 DAP message flags field 

1 1 Data Stream identification field (STREAMID) 

1 2 Length field (LENGTH) 

1 3 Length extension field (LEN2 5 6) 

1 4 Bit count field (BITCNT) 

1 5 System-specific field (SYSPEC) 

Access complete message errors 

07 00 Unknown field 

1 DAP message flags field (FLAGS) 

1 1 Data stream identification field (STREAMID) 

1 2 Length field (LENGTH) 

1 3 Length extension field (LEN2 5 6) 

1 4 Bit count field (BITCNT) 

20 Access complete function field (CMPFUNC) 

2 1 File options field (FOP) 

22 Checksum field (CHECK) 

Key definition message errors 

12 00 Unknown field 

1 DAP message flags field (FLAGS) 

1 1 Data stream identification field (STREAMID) 

1 2 Length field (LENGTH) 

13 Length extension field (LEN2 56) 

1 4 Bit count field (BITCNT) 

20 Key definition menu field (KEYMENU) 

21 Key option flags field (FLG) 

22 Data bucket fill quantity field (DFL) 
2 3 Index bucket fill quantity field (IFL) 

24 Key segment repeat count field (SEGCNT) 

(continued on next page) 
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Table E-2 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 1 0, 11 



Type Field 
Number Number 
(bits 6-11) (bits 0-5) 

25 
26 
27 
30 
31 
32 
33 
34 
35 
36 
37 
40 
41 
42 
43 
44 
45 

Allocation message errors 

13 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 
27 
30 
31 

Summary message errors 



14 



00 
10 
11 
12 
13 
14 



Field Description 

Key segment position field (POS) 
Key segment size field (SIZ) 
Key of reference field (REF) 
Key name field (KNM) 
Null key character field (NUL) 
Index area number field (IAN) 
Lowest level area number field (LAN) 
Data level area number field (DAN) 
Key data type field (DTP) 
Root VBN for this key field (RVB) 
Hash algorithm value field (HAL) 
First data bucket VBN field (DVB) 
Data bucket size field (DBS) 
Index bucket size field (IBS) 
Level of root bucket field (LVL) 
Total key size field (TKS) 
Minimum record size field (MRL) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Allocation menu field (ALLMENU) 

Relative volume number field (VOL) 

Alignment options field (ALN) 

Allocation options field (AOP) 

Starting location field (LOC) 

Related file identification field (RFI) 

Allocation quantity field (ALQ) 

Area identification field (AID) 

Bucket size field (BKZ) 

Default extension quantity field (DEQ) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

(continued on next page) 
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Table E-2 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 1 0, 1 1 



Type Field 
Number Number 
(bits 6-11) (bits 0-5) 

20 
21 
22 
23 
24 

Date and time message errors 

15 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 
26 
27 

Protection message errors 

16 00 
10 
11 
12 
13 
14 
20 
21 
22 
23 
24 
25 

Name message errors 



17 



00 
10 

11 

12 
13 
14 



Field Description 

Summary menu field (SUMENU) 

Number of keys field (NOK) 

Number of areas field (NOA) 

Number of record descriptors field (NOR) 

Prologue version number (PVN) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Date and time menu field (DATMENU) 

Creation date and time field (CDT) 

Last update date and time field (RDT) 

Deletion date and time field (EDT) 

Revision number field (RVN) 

Backup date and time field (BDT) 

Physical creation date and time field (PDT) 

Accessed date and time field (ADT) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 

Protection menu field (PROTMENU) 

File owner field (OWNER) 

System protection field (PROTSYS) 

Owner protection field (PROTOWN) 

Group protection field (PROTGRP) 

World protection field (PROWLD) 



Unknown field 

DAP message flags field (FLAGS) 

Data stream identification field (STREAMID) 

Length field (LENGTH) 

Length extension field (LEN256) 

Bit count field (BITCNT) 



(continued on next page) 
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Table E-2 (cont.): DAP Miccode Values for Use with Maccode Values of 2, 1 0, 1 1 

Type Field 
Number Number 

(bits 6-1 1 ) (bits 0-5) Field Description 

20 Name type field (NAMETYPE) 

2 1 Name field (NAMESPEC) 
Access control list message errors (reserved for future use) 



00 


Unknown field 


10 


DAP message flags field (FLAGS) 


11 


Data stream identification field (STREAMID) 


12 


Length field (LENGTH) 


13 


Length extension field (LEN256) 


14 


Bit count field (BITCNT) 


15 


System-specific field (SYSPEC) 


20 


Access control list repeat count field (ACLCNT) 


21 


Access control list entry field (ACL) 
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Table E-3 follows. The error code number (column 1) is contained in bits 0-11. For 
corresponding RMS or FCS status codes, refer to the appropriate DECnet or RMS docu- 
mentation for each remote system. 

Table E-3: DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



Error Code 




(bits 0-11) 


Error Description 





Unspecified error 


1 


Operation aborted 


2 


Fl 1-ACP could not access file 


3 


File activity precludes operation 


4 


Bad area ID 


5 


Alignment options error 


6 


Allocation quantity too large or value 


7 


Not ANSI D format 


10 


Allocation options error 


11 


Invalid (that is, synchronous) operation at AST level 


12 


Attribute read error 


13 


Attribute write error 


14 


Bucket size too large 


15 


Bucket size too large 


16 


BLN length error 


17 


Beginning of file detected 


20 


Private pool address 


21 


Private pool size 


22 


Internal RMS error condition detected 


23 


Cannot connect RAB 


24 


$ UPDATE changed a key without having attribute of XB$CHG set 


25 


Bucket format check-byte failure 


26 


RSTS/E close function failed 


27 


Invalid or unsupported COD field 



(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



Error Code 




(bits 0-11) 


Error Description 


30 


Fl 1-ACP could not create file (STV - system error code) 


31 


No current record (operation not preceded by get/find) 


32 


Fl 1-ACP deaccess error during close 


33 


Data area number invalid 


34 


RF A- accessed record was deleted 


35 


Bad device, or inappropriate device type 


36 


Error in directory name 


37 


Dynamic memory exhausted 


40 


Directory not found 


41 


Device not ready 


42 


Device has positioning error 


43 


DTP field invalid 


44 


Duplicate key detected; XB$DUP not set 


45 


Fl 1-ACP enter function failed 


46 


Operation not selected in ORG$ macro 


47 


End of file 


50 


Expanded string area too short 


51 


File expiration date not yet reached 


52 


File extend failure 


53 


Not a valid FAB (BID does not = FBIBID) 




Tllpo^il FAC^ for rpr*orH or*p ration or FR$PTTT not SPt for rrpatp 


55 


File already exists 


56 


Invalid file ID 


57 


Invalid flag-bits combination 


60 


File is locked by other user 



(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



Erro* Code 




(bits 0-11) 


Error Description 


61 


Fl l-ACP find function failed 


62 


File not found 


63 


Error in file name 


64 


Invalid file options 


65 


Device/file full 


66 


Index area number invalid 


67 


Invalid IFI value or unopened file 


70 


Maximum NUM (254) areas/key XABS exceeded 


71 


$INIT macro never issued 


72 


Operation illegal or invalid for file organization 


73 


Illegal record encountered (with sequential files only) 


74 


Invalid ISI value on unconnected RAB 


75 


Bad key buffer address (KBF = 0) 


76 


Invalid key field (KEY = or negative) 


77 


Invalid key of reference ($GET/$FIND) 


100 


Key size too large 


101 


Lowest level index area number invalid 


102 


Not ANSI-labeled tape 


103 


Logical channel busy 


104 


Logical channel number too large 


105 


Logical extend error; prior extend still valid 


106 


LOC field invalid 


JLU / 


Buffer-mapping error 


110 


Fl l-ACP could not mark file for deletion 


111 


MRN value = negative or relative key > MRN 


112 


MRS value = for fixed length records and/or relative files 




(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



Error Code 




(bits 0-11) 


Error Description 


113 


NAM block address invalid (NAM = or is not accessible 


114 


Not positioned to EOF (with sequential files only) 


115 


Cannot allocate internal index descriptor 


116 


Indexed file; primary key defined 


117 


RSTS/E open function failed 


120 


XABs not in correct order 


121 


Invalid file organization value 


122 


Error in file's prologue (reconstruct file) 


123 


POS field invalid (POS) > MRS; STV = XAB indicator) 


124 


Bad file date field retrieved 


125 


Privilege violation (OS denies access) 


126 


Not a valid RAB (BID does not = RB$BID) 


127 


Illegal RAC value 


130 


Illegal record attributes 


131 


Invalid record buffer address (either odd or not word aligned if BLK-IO) 


132 


File read error 


133 


Record already exists 


134 


Bad RFA value (RFA = 0) 


135 


Invalid record format 


136 


Target bucket locked by another stream 


137 


Fl 1-ACP remove function failed 


1 40 

1 t:U 


I? f*t*c\ff \ haI inn/I 


141 


Record not locked 


142 


Invalid record options 


143 


Error while reading prologue 


144 


Invalid RRV record encountered 



(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



Error Code 




/Kite fl 11\ 


error ueocupiion 


14} 


RAB stream currently iictive 


1 A6. 

14o 


Joad record size (KbZ > MKboriNUi = mks 11 tixed lengtn records) 


i An 

14/ 


Record too big for user's buffer 


1 en 


rTimary Key out 01 sequence ^kal — Kt>jj>;>t!,i^j ior i> r u 1 j 


1 C1 

151 


SHR field invalid for file (cannot share sequential files) 


ICO 

15^ 


mz Held invalid 


15? 


Stack too big for save area 


1 C4 


System directive error 


ICC 

155 


Index tree error 


1 50 


Error in file type extension on FNS is too big 




lllV<lilU L/U11C1 *IUUJ.C35 IU , Ul WU1U <llll£ilCU 11- JLJJLJV 1 


1 /^n 
lOU 


Invalid user buffer size (USZ = 0) 


1 £1 
101 


nnoi in vcimoii iiuiiidci 




Invalid volume number 


103 


nic wiuc ciior ^3 1 v — sy&icni ciiui luucj 


1 OtT 


Device is write locked 


1 


Error while writing prologue 


loo 


in ot a valid aad (@AAJt> = oaa; a i v = aajo indicator) 


10/ 


L/ciauii uiicciory inv<iiiu 


1 /U 


Cannot access argument list 


1 "7 1 
1/1 


Cannot close file 


1 // 


Cannot deliver AST 


173 


Channel assignment failure (STV = system error code) 


174 


Terminal output ignored due to (Ctrl/0 ) 


175 


Terminal input aborted due to (CTRL/Y ) 


176 


Default file name string address error 


177 


Invalid device ID field 



(continued on next page) 
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Table E-3 



(cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



Error Code 

(bits 0-1 1 ) Error Description 

200 Expanded string address error 

201 File name string address error 

202 FSZ field invalid 

203 Invalid argument list 

204 Known file found 

205 Logical name error 

206 Node name error 

207 Operation successful 

210 Inserted record had duplicate key 

211 Index update error occurred; record inserted 

212 Record locked, but read anyway 

213 Record inserted in primary key is okay; may not be accessible by secondary 
keys or RFA 

214 File was created, but not opened 

215 Bad prompt buffer address 

216 Asynchronous operation pending completion 

217 Quoted string error 

220 Record header buffer invalid 

221 Invalid related file 

222 Invalid resultant string size 

223 Invalid resultant string address 

224 Operation not sequential 

225 Operation successful 

226 Created file superseded existing version 

227 File name syntax error 

230 Timeout period expired 

231 FB $ BLK record attribute not supported 

232 Bad byte size 

(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0, 1 , 4, 5, 6, 7 



Error Code 




(bits 0-11) 


Error Description 


233 


Cannot disconnect RAB 


234 


Cannot get JFN for file 


235 


Cannot open file 


236 


Bad JFN value 


237 


Cannot position to end of file 


240 


Cannot truncate file 


241 


File currently in an undefined state; access is denied 


242 


File must be opened for exclusive access 


243 


Directory full 


244 


Handler not in system 


245 


Fatal hardware error 


246 


Attempt to write beyond EOF 


247 


Hardware option not present 


250 


Device not attached 


251 


Device already attached 


252 


Device not attachable 


253 


Shareable resource in use 


254 


Illegal overlay request 


255 


Block check or CRC error 


256 


Caller's nodes exhausted 


257 


Index file full 


260 


File header full 


261 


Accessed for write 


262 


File header checksum failure 


263 


Attribute control list error 


264 


File already accessed on LUN 


265 


Bad tape format 



(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 



UllUl V/UUC 




(bits 0-11) 


Error Description 


266 


Illegal operation on file descriptor block 


267 


Rename; two different devices 


270 


Rename; new file name already in use 


271 


Cannot rename old file system 


272 


File already open 


273 


Parity error on device 


274 


End of volume detected 


275 


Data overrun 


276 


Bad block on device 


277 


End of tape detected 


300 


No buffer space for file 


301 


File exceeds allocated space; no blocks left 


302 


Specified task not installed 


303 


Unlock error 


304 


No file accessed on LUN 


305 


Send/receive failure 


306 


Spool or submit command file failure 


307 


No more files 


310 


DAP file transfer checksum error 


311 


Quota exceeded 


312 


Internal network error condition detected 


313 


Terminal input aborted due to (CTRL/C ) 


314 


Data bucket fill size > bucket size in XAB 


315 


Invalid expanded string length 


316 


Illegal bucket format 


317 


Bucket size of LAN does not = IAN in XAB 



(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 
Error Code 

(bits 0-1 1 ) Error Description 

320 Index not initialized 

321 Illegal file attributes (corrupt file header) 

322 Index bucket fill size > bucket size in XAB 

323 Key name buffer not readable or writeable in XAB 

324 Index bucket will not hold two keys for key of reference 

325 Multibuffer count invalid (negative value) 

326 Network operation failed at remote node 

327 Record is already locked 

330 Deleted record successfully accessed 

331 Retrieved record exceeds specified key value 

332 Key XAB not filled in 

333 Nonexistent record successfully accessed 

334 Unsupported prologue version 

335 Illegal key of reference in XAB 

336 Invalid resultant string length 

337 Error updating RRVs; some paths to data may be lost 

340 Data types other than string limited to one segment in XAB 

341 Reserved 

342 Operation not supported over network 

343 Error on write behind 

344 Invalid wildcard operation 

345 Working set full (cannot lock buffers in working set) 

346 Directory listing: error in reading volume set name, directory name, or file 
name 

347 Directory listing: error in reading file attributes 

350 Directory listing: protection violation in trying to read the volume set, direc- 
tory, or file name 

(continued on next page) 
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Table E-3 (cont.): DAP Miccode Values for Use with Maccode Values 0,1,4, 5, 6, 7 
Error Code 



(bits 0-1 1 ) Error Description 

351 Directory listing: protection violation in trying to read file attributes 

352 Directory listing: file attributes do not exist 

353 Directory listing : unable to recover directory list after continue transfer (skip) 

354 Sharing not enabled 

355 Sharing page count exceeded 

356 UPI bit not set when sharing with BRO set 

357 Error in access control string 

360 Terminator not seen 

361 Bad escape sequence 

362 Partial escape sequence 

363 Invalid wildcard context value 

364 Invalid directory rename operation 

365 User structure (FAB/RAB) became invalid during operation 

366 Network file transfer mode precludes operation 

6000 User-defined errors 
to 

7777 
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Table E-4 follows. The message type number is contained in bits 0-11 
Table E-4: DAP Miccode Values for Use with Maccode Value 1 2 



Type 




Number 




(bits 0-1) 


Message Type 





Unknown message type 


1 


Configuration message 


2 


Attributes message 


3 


Access message 


4 


Control message 


5 


Continue transfer message 


6 


Acknowledge message 


7 


Access complete message 


10 


Data message 


11 


Status message 


12 


Key definition attributes extension message 


13 


Allocation attributes extension message 


14 


Summary attributes extension message 


15 


Date and time attributes extension message 


16 


Protection attributes extension message 


17 


Name message 


20 


Access control list extended attributes message 
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Transparent File Access Error Messages 



This appendix summarizes extended error messages for transparent file access opera- 
tions. The following messages are displayed by the TNT utility. 

Extended Error Message 

Can't get a handle to the network driver. 

Too many logical links already in use. The maximum number is 4. 
Error in node specification. 

The node name specification was not found in DECPARM.DAT. 

Unable to transmit user buffer. 

Invalid DAP message type received. 

Unsupported DAP flag field received. 

Invalid DAP message format received. 

Unexpected DAP message received. 

Unsupported DAP data type. 

Unsupported file organization. DECnet-DOS only supports sequential file organiza- 
tion. 

Remote system DAP buffer size is less than 128 bytes. 
The file to be accessed is not open. 
Error - unknown error. 
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The maximum record size has exceeded 128 bytes. 

The buffer size for the records contained in the remote input file is too small. 
Error in closing file. 
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Transporting DECnet-DOS Programs 



If you develop code to be transported to a DECnet-ULTRIX or any other system that 
supports the socket interface library, it is recommended that you use these suggestions: 

• The select function has a feature specific only to DECnet-DOS. The bit mask 
exceptfds is presently not supported by DECnet-ULTRIX. As a result, you cannot 
transport code that includes the exception bit mask. 

• Include a special prefix and compatibility mode header file in your DECnet-DOS 
program. 

• Define certain function call names depending upon which system compilation is to 
take place. For DECnet-DOS programs, the socket function calls - ioctl, read, 
write and close must be prefixed with an "s". 

An example compatibility header file is shown below: 



#i f def MSDOS 



# d e f i n e 


ioctKs, 


f, a) 


s i o c t L ( s , 


f, a) 


/* 


control */ 












/* 


socket i/o*/ 


# d e f i n e 


read ( s , 


bu f , L en ) 


s r e ad ( s , 


bu f , L en ) 


/* 


read from */ 












/* 


a socket */ 


#de f i ne 


wri te(s, 


bu f , I en ) 


swrite(s, 


bu f , L en ) 


/* 


write to */ 












/* 


a socket * / 


#de f i ne 


c Lose(s) 




scLose(s) 




/* 


close a * / 












/* 


socket */ 


# e n d i f 


/* MSDOS 


*/ 
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DECnet-DOS Programming Examples 



H . 1 Example Client Task Program 

The following networking program uses the DECnet-DOS socket interface. In this 
example, the client task tries to connect to a task on a remote node; send data and wait 
30 seconds for any incoming data before timing out or until the peer task decides to 
close down the link. 



/* 

* Include standard headers. 
*/ 

# include < s t d i o . h > 
/* 

* User defined symbols for conditional compilation. 
*/ 

# include "dnprefix.h" 
/* 

* Include some network interface headers. 
*/ 

# include " types. h" /* Type definitions, abstract data types 
*/ 

# include "time.h" /* Time data structures. 
*/ 

#include "dn.h" /* Network data structures and 

*/ 

/* definitions. 

*/ 



(continued on next page) 
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# include "socket. h" /* Socket interface layer definitions. 
*/ 

#include "sioctl.h" /* Socket I/O control functions. 
*/ 

#include "errno.h" /* Global user error definitions returned 
*/ 

/* in 'errno' . 

*/ 
/* 

* Cond i t i ona I i ze for DECnet-ULTRIX compatibility. 
*/ 

#ifndef MSDOS 

#define sclose(s) close(s) 
#define sioctl(s t f # a) ioctl(s,f,a) 
ff end i f 

#define SEQUENCED_PACKET 
tfdefine STREAM 1 

/* 

* Version string. 
*/ 

static char versionl] = "V1.01"; 

/* 

* Main line code. 
*/ 

main(argc f argv) 

i n t a r g c ; 

char *argv[ ] ; 



/* 




* Local 


data . 


*/ 




struct 


timeval tmv; 


char 


♦node, *object; 


u_cha r 


opt i ona l_s end [16]; 


u_char 


optional_receive[16]; 


u_cha r 


data_buf f erMOO] ; 


f ield32 


readfds, writefds; 


int 


r ec_l en ; 


int 


sock_type ; 


int 


sock ; 


int 


loop; 


int 


count ; 


int 


I en ; 


int 


i ndO; 


char 


b i o [ 1 3 ; 
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/* 

* Make sure there are a valid number of input arguments. 
*/ 

if (argc < 3) 
{ . 

printfC "Usage: test <node name or address>\ 
<#objnum or objnam>\n"); 
exi t(1 > ; 

} 

/* 

* Display our current version. 
*/ 

printf("\t\tSample - %s\n", aversion [0.]); 
/* 

* Set up optional data to send with connect. 
*/ 

strcpy(&optiona l_send [ ] , "hello"); 
/* 

* Attempt to connect to the object on the remote node. 
*/ 

rec_len = s i z eo f ( op t i ona l_r e c e i v e ) ; 

node = *++argv; 

object = *++argv; 

sock_type = SEQU ENCED_PACKET ; 

printf( "connecting to node \"%s\", object \"%s\"\n", 

node, object); 
if ((sock = dnet_conn(node, object, sock_type, 
&optional_sendC0], 

str len( "he I lo ") , 

&opt iona l_recei ve[03 , &rec_len)) < 0) 

{ 

ne r ro r ( "dne t_conn ") ; 
e x i t ( 1 ) ; 

} 

printf( "connect complete with node \"%s\",\ 
object \"Zs\"\n", node, object); 

/* 

* Check for returned optional data. 
*/ 

if ( r e c_ I e n ) 
{ 

puts( "optiona I data received:"); 

for (indO = 0; indO < rec_len; ind0++) 

{ 

printf(" %d", optiona l_receive[indO]); 

} 

puts( "") ; 

} 
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/* 

* Fill a data buffer with dummy data. 
*/ 

for (Loop = 0; Loop < s i z eo f ( d a t a_bu f f e r ) ; loop++) 
{ 

data_buf f er[ Loop] = Loop + 10; 

} 

/* 

* Try to send a dummy data buffer 10 times 

* to target object as Long as Link is stiLL active 
*/ 

Loop = 10; 
whiLe (Loop--) 
{ 

if ( dnet_eo f ( soc k ) = = 1) 

{ 

printf("Link is down.\n"); 

scLose(sock); 

e x i t ( 1 ) ; 

} 

if ((count = send(sock f &da t a_bu f f e r C ] , 

sizeof (data_buf f er) , 0)) < 0) 

{ 

perror( "write ") ; 
scLose(sock); 
e x i t ( 1 ) ; 

} 

} 

printf("data successfully sent to %s\n", node); 



/* 

* Now set the socket to nonblocking mode. 
*/ 

b i o C ] = 1 ; 

sioctUsock, FI0NBI0, SbioCO]); 



/* 

* CLean out the data buffer. 
*/ 

bz e ro ( &da ta_buf f e r [ ] , sizeof ( da t a_bu f f e r ) ) ; 
/* 

* Continue to receive data from target object untiL 

* disconnected. 
*/ 

whi Le (1 ) 
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/* 

* Check if Link is still active. 
*/ 

if ( dne t_eo f ( so c k ) == 1) 

{ 

printf<" link is down.Xn"); 
sclose(sock) ; 
e x i t ( 1 ) ; 

} 



/* 






* Now chec 


k to see if 


the socket has data 


* to read 


and timeout 


after 30 seconds. 


*/ 






readfds = 1 


<< sock; 




tmv . tv_sec 


= 30; 





if ((indO = select(sock + 1, Sreadfds, 0, 0, &tmv)) < 0) 
{ 

perror( "select"); 

} 

else 
{ 

if (indO == 0) 
{ 

p r i n t f ( "receive wait timed out.\n"); 

sclose(sock); 

e x i t ( 1 ) ; 

} 

} 

if ((count = recv(sock, Sda t a_bu f f e r [ ] , 

s i zeof (data_buf f er ) , 0)) < 0) 

{ 

if (errno != EW0ULDBL0CK) 
{ 

perror( "read") ; 
break; 

} 

else 

continue; 

} 

printf("data received (%d bytes) :\n", count); 
for (indO = 0; indO < count; i n d + + ) 

{ 

printf(" %d", da t a_bu f f e r C i ndO 1 ); 

} 

puts( "") ; 
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/* 

* Finish up. Make the socket Linger on close to allow 

* things to get cleaned. 
*/ 

if (setsockopt(sock, S0l_S0CKET, S0_L I NG E R , 0, 0) < 0) 

{ 

perror( "setsockopt ") ; 

} 

/* 

* Close the socket and exit program. 
*/ 

sclose(sock); 
e x i t ( ) ; 
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H.2 Example Client Transparent Task-to-Task Program 



The following program illustrates transparent task-to-task communication. It describes 
the functions that the client task uses to communicate over the network. 



/* 
* 

* Sample client program written in C that shows Transparent 

* Task-to-task using DECnet-DOS. 
* 

* When running this program, the command line argument should 

* look like a network task specification. See the following 

* examples as well as examples cited in the documentation: 

* For example: 
* 

* \\t\pcdos\\#100(to connect by object number) 

* \\t\pcdos\smi t h \ xx xx x \ \ T I M ES RV ( to connect by object name) 
* 

* After getting a handle (for example, by connecting to a 

* remote object), an attempt is made to write/send some data to 



* the 
* 


object and then close the handle. 




* 


All C include files and external functions 


are 


* 


distributed with the DECnet-DOS kit in the 


file 


* 
* 


DNETLIB.SRC. 




* 


When attempts to run this program fail, run 


the utility 


* 


TNT. EXE shipped with the DECnet-DOS kit to 


examine 


* 


DECnet errors. 




* 

*/ 







^include <stdio.h> 

#include "types. h" 

^include "scbdef.h" 

#include "errno.h" 



static char bufC100]; 
/* 

* Function(s) included in DNETLIB.SRC 
*/ 

extern int hopen(); 

extern int hwriteO, hcloseO; 



main(argc, argv) 
int a r g c ; 
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char *argv[ ] ; 
{ 

i n t i ; 
i n t j ; 
i n t ' I e n ; 
int h = 0; 

if (argc < 2) 
{ 

print f( "Usage: ttttst <TTT_network_task_string>\n") ; 
printf("\n example:\n"); 

printf("\t ttttst WW t\ \ pygmy \ \ \ \<#ob j ect_number>\n ") ; 
printf("\t or\n"); 

printf("\t ttttst W W t \ \ pygmy \ \ \ \<ob j e c t_name>\ n ") ; 
ex i t ( 1 ) ; 

} 

/* 

* FILL a dummy data buffer. 
*/ 

for (i = 0; i < sizeof(buf); i+ + ) 
bufCi] = i ; 

/* 

* Open file (access remote network object). 
*/ 

h = hopen(argvM ] , SCBC_HOPEN); 

if (h == ERROR) 

{ 

pe r ro r ( "\nopen ") ; 

printf("\n (run TNT. EXE to examine network error)"); 
ex i t ( 1 ) ; 

} 

printf ( "\nopen succeeded handle: %u (connected to object)", 
h); 

/* 

* Write to file (send data to remote object). 
*/ 

if (hwrite(h, SbuflO], sizeof(buf)) != sizeof(buf)) 

{ 

perror( "\nwrite") ; 

printf("\n (run TNT. EXE to examine network error)"); 

} 

else 

pr i nt f ( "\nwr i te succeeded (sent data to object)"); 

/* 

* Read from file handle (receive data from object, if any). 
*/ 

len = hread(h, &buf[0], s i z eo f ( buf ) ) ; 
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if (I en < 0) 
{ 

perror( "\nread") ; 

printf ( "\n (run TNT. EXE to examine network error)"); 

} 

else 
{ 

printf("\nread % u byte(s) (received from object)\n", 
I en ) ; 

for (i = i = 0; i < I en; i++, j+ + ) 

{ 

if ( j > 9 ) 

{ 

printf ( "\n") ; 
]' = 0; 

} 

printf ( " %4u", buf [i ] ) ; 

} 

} 



/* 

* Close file handle (disconnect link). 
*/ 

hclose(h) ; 

printf ( "\nf inished. ") ; 
exi t(0) ; 

} 
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H.3 Example Server Task Program 



The following networking program uses the DECnet-DOS socket interface. The exam- 
ple describes the activities of a DECnet-DOS server task. 



/* 



* Program - MIRROR 
★ 

* Copyright (C) 1985, All Rights Reserved, by 

* Digital Equipment Corporation, Maynard, Mass. 
* 

* This software is furnished under a license and may be used 

* and copied only in accordance with the terms of such license 

* and with the inclusion of the above copyright notice. This 

* software or any other copies thereof may not be provided or 

* otherwise made available to any other person. No title to 

* and ownership of the software is hereby transferred. 
* 

* The information in this software is subject to change without 

* notice and should not be construed as a commitment by 

* Digital Equipment Corporation. 
* 

* Digital assumes no responsibility for the use or reliability 

* of its software on equipment which is not supplied 

* by Digital. 



MODULE DESCRIPTION: 
Program MIRROR 

DECnet-DOS, mirror server, DECnet object 25 
Networks & Communications Software Engineering 
IDENT HISTORY: 



* V1 .00 



*/ 



20-Nov-85 

DECnet-DOS, Version 1.1 



# i n c I u d e 

# i n c I u d e 
#i nc lude 

# i n c I u d e 

# i n c I u d e 

# i n c I ude 

# i n c I ude 

# i n c I u d e 



<stdio.h> 
" t y p e s . h " 
"dnmsdos . h " 
"dn.h" 
"socket. h " 
"time.h" 
"err no . h " 
"scbdef.h" 



#define MAX_BUF_SIZE 2048 /* maximum loop data buffer */ 

struct sockaddr_dn sockaddr; /* accept connect data structure */ 

struct optdata_dn opt; /* optional data buffer */ 

char buf f [ M AX_BU F_S I Z E ] ; /* data buffer */ 

int Isock = -1; /* incoming connections on */ 

(continued on next page) 
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/* listening socket */ 
int sock = -1; /* data communications socket * / 

char moded]; /* accept mode */ 

char msg_vers i on [ ] = "MIRROR Listening (V1.1)"; 

/* 

* Sample DECnet-DOS server task. This task will bind itself 

* as DECnet object number 25, the standard DECnet object 

* reserved for a mirror task. When started, the mirror is the 

* only running task. To terminate, the user may 

* press any key . 
*/ 

mainCargc, argv) 
int a r g c ; 
char **argv; 

{ 

extern char *malloc(); 
extern char *dnet_ntoa ( ) ; 
int I e n ; 
int n f d s ; 

unsigned long read; 
struct timeval tmv; 

/* 

* Set up listening socket for incoming connect requests. 
*/ 

if ((Isock = socket(AF_DECnet, SOCK_SEQPACKET , 0)) < 0) 
mi r_exi t( "socket failed", errno) ; 

/* 

* Bind task to DECnet object 25. 
*/ 

bzero(&sockaddr, sizeof(sockaddr)); 
sockaddr . sdn_f am i I y = AF_DECnet; 
sockaddr . sdn_ob j num = 25; 

if (bind(lsock, &sockaddr, sizeof(sockaddr)) < 0) 
m i r_ex i t ( "b i nd failed", errno); 



/* 

* Set up listening socket to Listen for incoming connect 

* requests. Allow for up to 5 pending incoming 

* connect requests. 
*/ 

if (Listendsock, 5) < 0) 

m i r_ex i t ( " I i s t en failed", errno); 



/* 

* Listen for incoming connect requests until 

* there is keyboard input. 
*/ 

whi Le( 1 ) 

I 
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/* 

* DispLay mirror version message. 
*/ 

p r i n t f ( "\ n%s " , msg_vers i on ) ; 

/* 

* Poll listening socket for incoming connect request. 
*/ 

w hi I e ( 1 ) 

{ 

if ( m i r_k eyboa rd_i nput ( ) ) 
mi r_exit(NULL, 0); 

bzero(&tmv, sizeof(tmv)); 
read = 1 << Isock; 
nfds = Isock + 1; 

if (select(nfds, &read, 0, 0, Stmv) > 0) 
{ 

if (read & (1 << Isock)) 
break ; 

} 

} 

/* 

* Issue a deferred accept on the connect request - send 

* some optional data along with it. 
*/ 

modeCO] = ACC_DE FER ; 

if <setsockopt< Isock , DNPR0T0_NSP, DS0_ACCEPTM0DE , 
SmodeCO], s i z eo f ( mode ) ) < 0) 

{ 

m i r_ex i t < "set accept mode", 1); 

} 

len = sizeof(sockaddr); 

if ((sock = a c c ep t ( I so c k , &sockaddr, Slen)) < 0) 
mi r_exi t( "accept failed", errno); 

/* 

* Set up outgoing optional data - maximum mirror 

* data buffer size. 
*/ 

bzero(&opt, sizeof(opt)); 

opt.opt_optl = sizeof(unsigned short); 
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♦(unsigned short * ) &opt . opt_da ta [0 ] = MAX_BU F_S I ZE ; 
if (setsockopt ( sock , DNPR0T0_NSP, DS0_C0 N DAT A , Sopt, 
sizeof(opt)) < 0) 

{ 

m i r_ex i t ( "s et socket option - optional data", 

} 

errno) ; 

if (setsockoptC sock, DNPR0T0_NSP, DS0_C0NACCEPT , 
0, 0) < 0) 

{ 

m i r_ex i t ( "s et connect accept", 1 )'; 

} 

/* 

* Display peer information. 
*/ 

print f ( "\n"); 

p r i n t f ( "\ n Loop connect request from node: Y.s", 
dnet_ntoa(&sockaddr .sdn_add) ) ; 

if (sockaddr . sdn_obj num == 0) 

p r i n t f ( "\nR eques t i ng object name: %s", 
Ssockaddr. sdn_ob j name [ ] ) ; 

else 

pr i n t f ( "\nR eques t i ng object number: %d", 
sockaddr. sdn_ob j num) ; 
printf ( "\n"); 

/* 

* Loop data while link is still active and other end is 

* still sending data. 
*/ 

wh i I e( ! dne t_eof ( sock ) ) 
{ 

I en = MAX_BUF_SIZE; 

len = sread(sock, buff, &len); 

if (len == 0) 

{ 

if (dnet_eof (sock) ) 

mi r_exi t(NULL, 0); 

} 

else 
{ 

if (len < 0) 

m i r_ex i t ( "s r ead ", 1); 

} 

if CbuffCO] != 0) 
{ 

buff CO] = -1 ; 
len = 1 ; 
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} 

else 
{ 

buffCO] = 1 ; 

} 

if (swrite(sock, buff, Len) < 0) 
m i r_e x itC'swrite", 1 ) ; 

} 

/* 

* Finished with current data socket, close it up. 
*/ 

if (sock != -1) 
sc lose( sock) ; 

} 

} 

int m i r_keyboa rd_i nput < ) 

{ 

SCB scb; 

scb.AH = SCBC_CKSTAT; 
msdos ( &s cb ) ; 
if (scb.AL) 

r etu rn ( 1 ) ; 
return(O) ; 

} 

m i r_ex it(sp, err) 
char *sp; 
int err; 

{ 

if (sp != NULL) 

{ 

strcpy(buff, "\nmirror - "); 
strcat(buff, sp); 
perror(buff) ; 

} 

if (I sock != -1) 
sclose(lsock); 

i f (sock != -1 ) 
sclose(sock) ; 

exit(err) ; 

} 
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Listening for incoming client 

connections, 4-17, 6-39 
Load and execute a program, 2-20 
LOCALINFO, 6-40 
Logical link 

creating, 1-9 

exchanging data, 3-2 

rejecting, 1-10 

states, A-6 
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Logical link (Cont.) 

terminating activity on, 1-14, 

3-3,4-22 
testing state of, 5-13 
using SHUTDOWN call, 6-80 
using shutdown call, 4-33 

M 

MS-DOS function requests 
and TFARs, 2-8 
close, 2-12, 3-9 
create, 2-13, 3-10 
delete, 2-15 

find first matching file, 2-16 
find next matching file, 2-18 
load and execute a program, 

2- 20 

open, 2-21, 3-10 
read, 2-23, 3-12 
write, 2-25, 3-13 

N 

Named objects, 3-4 

and BIND call, 6-25 

and bind call, 4-9 

assigning to sockets, 4-9 
nerror, 5-27 

called when dnet conn fails 

to make connection, 5-27 

log output to stdout, 5-27 
Network access 

examining network task strings, 

3- 6 

intercepting requests for, 3-6 
Network file specifications 

file name strings, 2-8 

node specifications, 2-7 

requesting network access, 2-7 

string format, 2-7 
Network node database 

accessing information, 5-24 
Network object number, 1-6 

range of, 1-6 
Network process interface calls 

ABORT, 6-13 

ACCEPT, 6-15 

ATTACH, 6-21 

BIND, 6-24 



Network process interface calls (Cont.) 

CANCEL, 6-27 

CONNECT, 6-29 

DETACH, 6-34 

DISCONNECT, 6-36 

GETSOCKOPT, 6-73 

LISTEN, 6-38 

LOCALINFO, 6-40 

PEERADDR, 6-43 

RCVD, 6-46 

RCVOOB, 6-52 

SELECT, 6-57 

SEND, 6-62 

SENDOOB, 6-68 

SETSOCKOPT, 6-73 

SHUTDOWN, 6-80 

SIOCTL, 6-82 

SOCKADDR, 6-85 
Network process interface calls 

summary, 6-11 to 6-12 
Network task name 

defined with bind call, 1-6 
Network task specifications, 3-4 

format of, 3-4 
Node address, 1-6 

converting binary to DECnet ASCII 
string, 5-17 

converting DECnet ASCII string to 
binary, 5-8 

DECnet ASCII string, 5-19 
Node information 

retrieving, 5-16 
Node name, 1-6 

searching with dnet htoa, 

5-17 
Node names 

specifying as SYS $ NET, 3-10 
Node specifications, 2-7, 3-4 

and access control data, 2-7 

format of, 2-7, 3-5 

format using dnet conn, 5-10 

Nonblocking I/O 

defined, 1-6 

error messages when receiving 
normal data, 4-20, 4-39 

error messages when receiving 
out-of-band data, 4-2 1 

error messages when sending 
normal data, 4-27, 4-41, 6-66 
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Nonblocking I/O (Cont.) 

error messages when sending 
out-of-band data, 4-28, 6-72 

receiving normal data, 1-12 

sending normal data, 1-12 
Nonblocking synchronous I/O 

defined, 6-9 
Nontransparent communication 

network process interface calls, 
6-1 

using socket interface calls, 4-5 
Nontransparent task-to-task 
communication, 1-9 

socket interface calls, 1-9 
Numbered objects, 3-4 

and BIND call, 6-25 

and bind call, 4-9 

o 

On-line help 

displaying TNT commands, 
2-10, 3-7 

Open, 2-21, 3-10 

Optional user data 

closing the logical link, 1-14 
passed with CONNECT call, 6-3 1 
passed with connect call, 4-11 
size of, 1-6 

when disconnecting logical link, 
1-6 

when requesting logical link, 1-6 
Out-of-band messages, 1-13 
and blocking I/O, 1-13 
and nonblocking I/O , 1-13 
and send call, 4-26 
checked by SELECT call, 6-59 
checked by select call, 4-23 
receiving, 4-19 
size of, 1-13 

using MSG__OOB flag, 4-19, 
4-26 

Outgoing proxy logins 
defined, 5-9 

passed with dnet conn, 5-9 



Passwords 

and dnet conn, 5-9 



Peeking at message 

using RCVD and MSG PEEK 

flag, 6-48 

using RCVOOB and MSG PEEK 

flag, 6-55 
Peer sockets 

retrieving name with getpeername, 
4-13 

retrieving name with PEERADDR, 
6-44 
PEERADDR, 6-43 
perror, 5-28 

log output to stdout, 5-28 

R 

RCVD, 6-46 

and MSG ASYNC flag, 6-50 

and MSG CALLBACK flag, 6-50 

and MSG NEOM flag, 6-50 

and MSG PEEK flag, 6-50 

asynchronous mode described, 6-48 
RCVOOB, 6-52 

asynchronous mode described, 6-54 
Read, 2-23, 3-12 
Real-time Scheduler, 5-2 1 
Receiving data 

read multi-part message set with 
MSG NEOM flag, 6-48 

using RCVD, 6-48 

using recv or sread call, 4-19 
Record formats 

fixed length, 2-3 

stream, 2-3 

undefined, 2-3 

variable length, 2-3 

variable- with-fixed length control, 
2-3 
recv, 4-19 

Rejecting connection requests, 1-10 
Remote file access 

node name string, 2-2 

s 

SCH 

see Real-time Scheduler 
sclose, 4-22, G-l 
SELECT, 6-57 

and MSG ASYNC flag, 6-60 
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SELECT (Cont.) 

and MSG CALLBACK flag, 

6-60 

asynchronous mode described, 
6-59 

checking I/O status of sockets, 
6-59 

managing ACCEPT, SEND, SENDOOB, 
RCVD and RCVOOB calls, 6-59 
select, 4-23 

checking I/O status of sockets, 4-23 
SEND, 6-62 

and MSG__ASYNC flag, 6-65 

and MSG CALLBACK flag, 6-65 

and MSG NBOM flag, 6-65 

and MSG NEOM flag, 6-65 

asynchronous mode described, 6-64 
send, 4-26 
Sending data 

multi-part message set with MSG NEOM 

and MSG NBOM flags, 6-64 

using SEND call, 6-64 

using send or swrite call, 4-26 
SENDOOB, 6-68 

and MSG ASYNC flag, 6-70 

and MSG CALLBACK flag, 6-70 

asynchronous mode described, 6-70 
Sequential files, 2-3 
Server task 

and bind call, 4-9 

defined, 1-4 

using BIND call, 6-25 
SETSOCKOPT, 6-73 
setsockopt, 4-29 
SHUTDOWN, 6-80 
shutdown, 4-33 
SIOCTL, 6-82 
sioctl, 4-34, G-l 

prevent program hangs on stream 
sockets, 4-23 
SOCKADDR, 6-85 
socket, 4-36 
Socket interface 

sample calling sequence, 4-6 
Socket interface calls, 4-5 

accept, 4-7 

bind, 4-9 

connect, 4-11 

getpeername, 4-13 



Socket interface calls (Cont.) 
getsockname, 4-15 
getsockopt, 4-29 
listen, 4-17 
recv, 4-19 
sclose, 4-22 
select, 4-23 
send, 4-26 
setsockopt, 4-29 
shutdown, 4-33 
sioctl, 4-34 
socket, 4-36 
sread, 4-38 
swrite, 4-40 

used by C programs, 1-9, 4-5 
Socket interface calls summary, 4-5 
Socket names 

retrieving name with getsockname, 
4-15 

retrieving name with SOCKADDR, 
6-86 

used for listening operations, 1-9, 
4-9 

Socket numbers, 1-9, 4-17, 4-26 
and accept call, 4-7 
checked by SELECT call, 6-59 
checked by select call, 4-23 
range of, 4-23, 6-59 
renumbering with SIOCTL call, 6-83 
renumbering with sioctl call, 4-34 
returned by ACCEPT call, 6-17 
returned by socket call, 4-36 
used for listening operations, 4-9 
using with network process interface 
calls, 6-11 

Socket options, 4-29 to 4-31, 6-75 to 
6-77 

retrieving with GETSOCKOPT, 6-75 
retrieving with getsockopt, 4-29 
setting with SETSOCKOPT, 6-75 
setting with setsockopt, 4-29 

Socket types 
see Appendix A 

Sockets 

assigning names, 1-9 
controlling I/O operations of, 4-34, 
6-83 

creating, 1-9, 4-36, 6-17 
deactivating, 1-14 
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Sockets (Cont.) 

deactivating with sclose call, 
4-22 

defined, 1-4 

detaching, 6-13 

exchanging data, 1-4 

peer, 4-13, 6-44 

sequenced, 1-4 

stream, 1-4 
sread, 4-38, G-l 
stdout 

nerror log output to, 5-27 
perror log output to, 5-28 
swrite, 4-40, G-l 



Target task 

accessing by object name, 3-4 
accessing by object number, 3-4 
defined as named object, 3-4 
defined as numbered object, 3-4 

Target task specifications 
format of , 3-5 

format using dnet conn, 5-11 

Terminating logical link 

using DETACH call, 6-35 

using sclose call, 4-22 
Terminating logical links 

using ABORT, 6-13 
TFA 

see Transparent File Access utility 
TFARs 

see Transparent File Access 
Routines 

TNT 

see Transparent Network Test 
utility 

Transparent communication, 1-7 
access control data, 3-2 
and assembly language, 3-1 
and high level languages, 3-1 
capabilities, 1-7, 3-1 
creating a logical link, 3-2 
exchanging data, 3-2 
handshaking sequence, 3-2 
terminating activity on link, 3-3 
using MS-DOS function requests, 
3-3 



Transparent communication function 
requests 

close, 3-9 

create, 3-10 

open, 3-10 

read, 3-12 

write, 3-13 
Transparent communication function 

requests summary, 3-3 
Transparent file access, 2-1 

error messages, F-l to F-2 

initiating, 2-2 

using MS-DOS function requests, 2-2 
Transparent file access error messages 

see Appendix F 
Transparent file access function 
requests 
summary, 2-11 
Transparent file access functions 

close, 2-12 

create, 2-13 

delete, 2-15 

find first matching file, 2-16 

find next matching file, 2-18 

load and execute a program, 2-20 

open, 2-21 

read, 2-23 

write, 2-25 
Transparent File Access Routines 

accessing remote files, 2-2 
Transparent File Access utility 

deinstalling with TNT, 2-10 

displaying network status of, 2-9 

installing, 2-1 

programming considerations, 2-1 1 

traps MS-DOS interrupt 2 1H, 2-10 
Transparent Network Task utility 

extended error support, 3-6 

invoking, 3-6 

on-line help, 3-7 

returns DAP messages, 2-8 
Transparent Network Test utility, 2-8 

invoking, 2-9 

on-line help, 2-10 
Transparent Task-to-Task utility 

deinstalling with TNT, 3-8 

displaying network status of, 3-6 

installing, 3-3 

programming considerations, 3-8 
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Transparent Task-to-Task utility (Cont.) 
traps MS-DOS interrupt 2 1H, 3-8 

Transporting DECnet-DOS programs 
and socket interface calls, G-l 
compatibility header file, G-l 

TTT 

see Transparent Task-to-Task utility 

u 

ULTRIX error completion codes, C-l 
to C-3 

w 

Write, 2-25, 3-13 

8086/8088 registers 

and MS-DOS function requests, 3-8 
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